adamantite 0.45.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 +368 -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/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 → 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 -207
- 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 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/
|
|
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
|
|
@@ -356,8 +434,9 @@ ignores the `vitest/*` rules of an override that does not enable the `vitest` pl
|
|
|
356
434
|
### The react-strict preset
|
|
357
435
|
|
|
358
436
|
`adamantite/lint/react-strict` keeps state and side effects out of React feature code. Use
|
|
359
|
-
it together with `adamantite/lint/react`. It
|
|
360
|
-
|
|
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.
|
|
361
440
|
|
|
362
441
|
`adamantite/no-react-state-hooks` reports calls to `useState`, `useReducer`, `useEffect`,
|
|
363
442
|
`useLayoutEffect`, `useSyncExternalStore`, `useMemo`, and `useCallback` imported from
|
|
@@ -391,23 +470,17 @@ export default defineConfig({
|
|
|
391
470
|
|
|
392
471
|
Each option replaces its default list.
|
|
393
472
|
|
|
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
|
|
473
|
+
The React Doctor package exports more than 900 rules. The preset enables only rules that run on one file
|
|
403
474
|
and that the native `react`, `react-hooks`, `jsx-a11y`, and `unicorn` rules do not already
|
|
404
475
|
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`).
|
|
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
|
|
406
479
|
TanStack Query and TanStack Start rules are not in this preset. See
|
|
407
480
|
[ADR 0005](docs/adr/0005-curate-react-doctor-rules.md) for the criteria.
|
|
408
481
|
|
|
409
|
-
|
|
410
|
-
|
|
482
|
+
React Doctor checks also run in hook modules where state and effect hooks are allowed.
|
|
483
|
+
Some React Doctor rules
|
|
411
484
|
skip test files and fixtures by path, such as `__tests__/` and `*.test.tsx`.
|
|
412
485
|
|
|
413
486
|
`oxlint-plugin-react-doctor` has a modified MIT license. It needs written permission from
|
|
@@ -416,11 +489,15 @@ as a hosted product. Read the
|
|
|
416
489
|
[license](https://www.npmjs.com/package/oxlint-plugin-react-doctor?activeTab=code) before
|
|
417
490
|
you select the preset.
|
|
418
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
|
+
|
|
419
496
|
### The tanstack preset
|
|
420
497
|
|
|
421
498
|
`adamantite/lint/tanstack` holds opinions for TanStack Query (`@tanstack/react-query`) in
|
|
422
499
|
apps that preload queries in route loaders, such as TanStack Router and TanStack Start apps.
|
|
423
|
-
|
|
500
|
+
It needs no extra package.
|
|
424
501
|
|
|
425
502
|
- `adamantite/query-from-loader` reports `useQuery`, `useSuspenseQuery`, `useInfiniteQuery`,
|
|
426
503
|
and `useSuspenseInfiniteQuery` calls in route files that take a plain options object or a `queryOptions()`
|
|
@@ -441,9 +518,8 @@ A route file is a file that calls a route factory from `@tanstack/react-router`,
|
|
|
441
518
|
the query, so components outside route files can define their queries inline.
|
|
442
519
|
`query-from-loader` checks one file at a time. It cannot prove that a loader preloads the
|
|
443
520
|
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).
|
|
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).
|
|
447
523
|
|
|
448
524
|
### The effect preset
|
|
449
525
|
|
|
@@ -454,43 +530,77 @@ simpler replacement (`catch-all-to-map-error`). The rules come from
|
|
|
454
530
|
[@effect/tsgo](https://github.com/Effect-TS/tsgo), the Effect Language Service for
|
|
455
531
|
TypeScript-Go, and need Oxlint's type-aware mode.
|
|
456
532
|
|
|
457
|
-
The
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
- `
|
|
464
|
-
`
|
|
465
|
-
- `
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
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.
|
|
469
564
|
|
|
470
565
|
When you select the preset, `adamantite init` does these steps:
|
|
471
566
|
|
|
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.
|
|
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.
|
|
481
573
|
- Sets `ignoreDependencies.effect` in `knip.config.ts`, because no package has the name
|
|
482
574
|
`@effect/language-service`.
|
|
483
575
|
|
|
484
576
|
`adamantite doctor` reports each missing part, and `adamantite update` keeps
|
|
485
|
-
`@effect/tsgo` on its pinned version. Each `@effect/tsgo` release
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
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.
|
|
587
|
+
|
|
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`.
|
|
489
599
|
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
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.
|
|
494
604
|
|
|
495
605
|
The rules read their options from the tsconfig entry. For example, `unstable-api-usage`
|
|
496
606
|
reports each use of an API marked `@stability unstable`. To allow a module on purpose, list
|
|
@@ -502,7 +612,7 @@ it in `allowedUnstableApis`:
|
|
|
502
612
|
"plugins": [
|
|
503
613
|
{
|
|
504
614
|
"name": "@effect/language-service",
|
|
505
|
-
"diagnostics":
|
|
615
|
+
"diagnostics": true,
|
|
506
616
|
"allowedUnstableApis": ["effect/cli"],
|
|
507
617
|
},
|
|
508
618
|
],
|
|
@@ -521,10 +631,55 @@ as `Date.now()` or `process.env`, in code that is not Effect code. Inside Effect
|
|
|
521
631
|
reports them, because `Clock`, `Random`, and `Config` let tests control them. See
|
|
522
632
|
[ADR 0007](docs/adr/0007-effect-preset-patches-oxlint.md) for the criteria.
|
|
523
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
|
+
|
|
524
678
|
### The strict preset
|
|
525
679
|
|
|
526
|
-
`adamantite/lint/strict` holds framework-neutral opinions. Use it with any other preset.
|
|
527
|
-
|
|
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.
|
|
528
683
|
|
|
529
684
|
- `adamantite/no-overzealous-destructuring` reports destructuring patterns nested more than
|
|
530
685
|
`maxDepth` levels deep (default 2), such as `const { data: { user: { name } } } = query`,
|
|
@@ -532,6 +687,26 @@ reports them, because `Clock`, `Random`, and `Config` let tests control them. Se
|
|
|
532
687
|
element does not count. Keep the object and read its members, or split the pattern.
|
|
533
688
|
- `typescript/consistent-type-assertions` bans type assertions. `as const` stays allowed,
|
|
534
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`.
|
|
535
710
|
|
|
536
711
|
Set `maxDepth` and `maxProperties` to change the destructuring limits:
|
|
537
712
|
|
|
@@ -549,9 +724,11 @@ export default defineConfig({
|
|
|
549
724
|
})
|
|
550
725
|
```
|
|
551
726
|
|
|
552
|
-
### The
|
|
727
|
+
### The Tailwind preset
|
|
728
|
+
|
|
729
|
+
The preset uses upstream `shadcn/*` rule names and `settings.shadcn` keys.
|
|
553
730
|
|
|
554
|
-
`adamantite/lint/
|
|
731
|
+
`adamantite/lint/tailwind` needs Tailwind v4 and the `@shadcn/lint` package. `adamantite init`
|
|
555
732
|
installs the pinned version when you select the preset, and `adamantite doctor` and
|
|
556
733
|
`adamantite update` keep it on that version. If you add the preset by hand, install
|
|
557
734
|
`@shadcn/lint` as a devDependency too. The plugin finds your components and theme
|
|
@@ -561,11 +738,11 @@ components live elsewhere, set `settings.shadcn.ui`:
|
|
|
561
738
|
|
|
562
739
|
```ts
|
|
563
740
|
import core from "adamantite/lint"
|
|
564
|
-
import
|
|
741
|
+
import tailwind from "adamantite/lint/tailwind"
|
|
565
742
|
import { defineConfig } from "oxlint"
|
|
566
743
|
|
|
567
744
|
export default defineConfig({
|
|
568
|
-
extends: [core,
|
|
745
|
+
extends: [core, tailwind],
|
|
569
746
|
ignorePatterns: core.ignorePatterns,
|
|
570
747
|
settings: { shadcn: { ui: "@/ds" } },
|
|
571
748
|
})
|
|
@@ -580,21 +757,23 @@ contracts, and custom messages.
|
|
|
580
757
|
|
|
581
758
|
## Custom rules
|
|
582
759
|
|
|
583
|
-
Custom rules are Oxlint rules that your project writes and owns. Each file in
|
|
584
|
-
`.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
|
|
585
762
|
and enables each rule as `error` under the `project` plugin, so `no-process-env.ts` becomes
|
|
586
763
|
`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
|
|
764
|
+
that starts with `_`, such as `_helpers.ts`, is a helper. Declaration files and optional
|
|
765
|
+
`.test.*` files are also excluded from plugin loading.
|
|
588
766
|
|
|
589
767
|
```text
|
|
590
|
-
.adamantite/
|
|
768
|
+
.adamantite/lint/
|
|
591
769
|
no-process-env.ts # enabled as project/no-process-env
|
|
770
|
+
no-process-env.test.ts # optional test, skipped by the plugin
|
|
592
771
|
_helpers.ts # skipped
|
|
593
772
|
```
|
|
594
773
|
|
|
595
774
|
```ts
|
|
596
|
-
// .adamantite/
|
|
597
|
-
import { defineRule } from "adamantite/rules"
|
|
775
|
+
// .adamantite/lint/no-process-env.ts
|
|
776
|
+
import { defineRule } from "adamantite/rules/plugin"
|
|
598
777
|
|
|
599
778
|
export default defineRule({
|
|
600
779
|
meta: {
|
|
@@ -616,7 +795,7 @@ export default defineRule({
|
|
|
616
795
|
```ts
|
|
617
796
|
// oxlint.config.ts
|
|
618
797
|
import core from "adamantite/lint"
|
|
619
|
-
import custom from "adamantite/
|
|
798
|
+
import custom from "adamantite/rules"
|
|
620
799
|
import { defineConfig } from "oxlint"
|
|
621
800
|
|
|
622
801
|
export default defineConfig({
|
|
@@ -629,20 +808,64 @@ export default defineConfig({
|
|
|
629
808
|
it to every generated config. It takes these options:
|
|
630
809
|
|
|
631
810
|
- `dir`: the rules folder. A relative path resolves from the file that calls `custom()`, not
|
|
632
|
-
from the working directory. Default: `.adamantite/
|
|
811
|
+
from the working directory. Default: `.adamantite/lint`.
|
|
633
812
|
- `name`: the plugin name that prefixes each rule. Default: `project`.
|
|
634
813
|
- `rules`: severity or options for a rule, by rule name without the prefix, such as
|
|
635
814
|
`{ "no-process-env": "warn" }`.
|
|
636
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
|
+
|
|
637
855
|
Rule files run with Node.js type stripping, so use erasable TypeScript only: no `enum`,
|
|
638
856
|
`namespace` with values, or parameter properties. Rules get no type information. A rule
|
|
639
857
|
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
|
-
|
|
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.
|
|
643
864
|
|
|
644
865
|
`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.
|
|
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.
|
|
646
869
|
|
|
647
870
|
### Custom rules in a monorepo
|
|
648
871
|
|
|
@@ -652,7 +875,7 @@ root rules extends the root config:
|
|
|
652
875
|
|
|
653
876
|
```ts
|
|
654
877
|
// packages/web/oxlint.config.ts
|
|
655
|
-
import custom from "adamantite/
|
|
878
|
+
import custom from "adamantite/rules"
|
|
656
879
|
import { defineConfig } from "oxlint"
|
|
657
880
|
import root from "../../oxlint.config.ts"
|
|
658
881
|
|
|
@@ -665,14 +888,15 @@ extends it loads the same rules:
|
|
|
665
888
|
|
|
666
889
|
```ts
|
|
667
890
|
// tooling/lint/index.ts
|
|
668
|
-
import custom from "adamantite/
|
|
891
|
+
import custom from "adamantite/rules"
|
|
669
892
|
|
|
670
893
|
export default custom({ dir: "rules", name: "acme" })
|
|
671
894
|
```
|
|
672
895
|
|
|
673
896
|
Run `adamantite rule add <name> --dir tooling/lint/rules` to add a rule to that folder.
|
|
674
897
|
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
|
|
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
|
|
676
900
|
`dir` and `name` when they are string literals.
|
|
677
901
|
|
|
678
902
|
## Requirements and boundaries
|
|
@@ -692,16 +916,38 @@ relative imports and imports of workspace packages to find the `custom()` calls.
|
|
|
692
916
|
|
|
693
917
|
## Agent skill
|
|
694
918
|
|
|
695
|
-
|
|
696
|
-
|
|
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):
|
|
697
940
|
|
|
698
941
|
```sh
|
|
699
942
|
npx skills add adelrodriguez/adamantite --list
|
|
700
943
|
npx skills add adelrodriguez/adamantite --skill adamantite
|
|
701
944
|
```
|
|
702
945
|
|
|
703
|
-
|
|
704
|
-
|
|
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`,
|
|
705
951
|
after you approve it. pnpm creates the directory only when the agent that runs pnpm sets an
|
|
706
952
|
environment variable that identifies it, such as `CLAUDECODE` for `.claude/skills`.
|
|
707
953
|
Otherwise, if no skill directory exists, the install fails, so create one before you
|