adamantite 0.45.0 → 0.47.0

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