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.
Files changed (60) hide show
  1. package/README.md +368 -122
  2. package/dist/index.js +638 -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 +0 -1
  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 +940 -31
  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/runtime-CVZPDpfE.js +11 -0
  53. package/package.json +79 -18
  54. package/skills/adamantite/SKILL.md +112 -207
  55. package/skills/adamantite/references/custom-rules.md +120 -0
  56. package/skills/adamantite/references/lint-rules.md +158 -0
  57. package/skills/adamantite/references/setup.md +64 -0
  58. package/dist/presets/lint/antislop.js +0 -28
  59. package/dist/presets/lint/react-doctor.js +0 -20
  60. package/dist/presets/lint/shadcn.d.ts +0 -5
@@ -1,221 +1,126 @@
1
1
  ---
2
2
  name: adamantite
3
- description: Configures and maintains Adamantite linting, formatting, type-safety, analysis, editor, and CI tooling in TypeScript projects. Use when initializing Adamantite, running its checks, updating managed dependencies, or following Doctor findings in an existing installation.
3
+ description: Use when setting up Adamantite, running its checks, repairing Doctor findings, updating managed dependencies, hardening coding standards, or writing and testing custom rules.
4
4
  metadata:
5
5
  type: core
6
6
  library: adamantite
7
- library_version: "0.37.0"
7
+ library_version: "0.45.0"
8
8
  sources:
9
9
  - "adelrodriguez/adamantite:src/cli.ts"
10
- - "adelrodriguez/adamantite:src/commands/*.ts"
11
- - "adelrodriguez/adamantite:src/lib/workspace/custom-rules.ts"
10
+ - "adelrodriguez/adamantite:src/commands/**/*.ts"
11
+ - "adelrodriguez/adamantite:src/lib/execution/skill.ts"
12
+ - "adelrodriguez/adamantite:src/lib/toolchain/index.ts"
13
+ - "adelrodriguez/adamantite:src/lib/integrations/tooling/oxlint/plugins/**/*.ts"
14
+ - "adelrodriguez/adamantite:src/lib/integrations/tooling/knip/config.ts"
15
+ - "adelrodriguez/adamantite:src/lib/workspace/custom-rules/*"
16
+ - "adelrodriguez/adamantite:presets/lint/*.ts"
17
+ - "adelrodriguez/adamantite:presets/rules/*.ts"
12
18
  ---
13
19
 
14
20
  # Adamantite
15
21
 
16
- Adamantite is an opinionated preset package and CLI for modern TypeScript projects. Run
17
- commands from the target project's root and use its detected package manager.
18
-
19
- ## Quick start
20
-
21
- For a human-driven setup, run `npx adamantite init`. For an agent, prefer explicit
22
- non-interactive setup. Setup flags require `--non-interactive`, and at least one
23
- `--script` is required:
24
-
25
- ```shell
26
- npx adamantite init --non-interactive --script check --script fix --typescript --agents
27
- ```
28
-
29
- Repeat `--script`, `--preset`, and `--editor` for multiple values. Available values are:
30
-
31
- - Scripts: `check`, `fix`, `analyze`. In a detected monorepo, `analyze` also installs Sherif.
32
- - Presets: `react`, `react-strict`, `react-doctor`, `tanstack`, `nextjs`, `vue`, `effect`, `jest`,
33
- `vitest`, `node`, `strict`, `antislop`, `shadcn`;
34
- editors: `vscode`, `zed`
35
- - Optional flags: `--typescript`, `--install-extensions`, `--github-actions`, `--agents`,
36
- `--overwrite-scripts`
37
-
38
- The `react-strict` preset needs no extra package. Its `adamantite/no-react-state-hooks` rule
39
- reports React state, effect, and memoization hooks outside hook modules (`useCart.ts`,
40
- `use-cart.ts`, and files under `hooks/`), and each message tells what to do instead. Do not move a hook call into
41
- a hook module only to silence the rule: follow the message. Set the rule's `allow` option
42
- when the project keeps hooks elsewhere.
43
-
44
- The `strict` preset needs no extra package either. Its `adamantite/no-overzealous-destructuring`
45
- rule reports destructuring nested more than 2 levels deep or object patterns with more than 5
46
- properties; keep the object and read its members, or split the pattern. Do not raise
47
- `maxDepth` or `maxProperties` only to silence a report. The preset also bans type assertions
48
- outside tests.
49
-
50
- The `tanstack` preset needs no extra package. Its `adamantite/query-from-loader` rule reports
51
- TanStack Query hooks in route files (files that call `createFileRoute`, `createRoute`, or another
52
- route factory from `@tanstack/react-router`) that take a plain options object or a `queryOptions()` call made inside a
53
- function; define the query once with `queryOptions()` at module scope or in an exported factory,
54
- preload it in the route loader with `ensureQueryData()`, and pass the same options to the hook. For
55
- `useInfiniteQuery` and `useSuspenseInfiniteQuery`, use `infiniteQueryOptions()` and
56
- `ensureInfiniteQueryData()`. Its
57
- `adamantite/no-query-data-in-state` rule reports `useState` initialized from query data; read the
58
- value from the query result and keep only the user's edits in state. Do not wrap options in a
59
- spread object, or move the hook out of the route file, only to silence `query-from-loader`.
60
-
61
- The `jest` and `vitest` presets apply their rules only to the files that the test runner runs as
62
- tests by default, which each preset exports as `testFiles`. When the project keeps tests in other
63
- files, replace the preset in `extends` with an override of the project's own:
64
- `{ files: [...], plugins: vitest.plugins, rules: { ...vitest.rules } }`. Change a test rule in such
65
- an override, not in the top-level `rules`, which do not reach test files. Keep `plugins` in the
66
- override, because Oxlint ignores its `vitest/*` rules without it.
67
-
68
- The `react-doctor` preset requires the `react` preset and the `oxlint-plugin-react-doctor`
69
- package, which `init` installs at a pinned version and doctor and `update` keep in sync. It
70
- enables curated React Doctor rules for React state and effect misuse, such as
71
- `no-effect-event-handler` and `no-fetch-in-effect`, and adds to `react-strict`. The package has
72
- a modified MIT license: using it as machine learning training data or selling it as a
73
- hosted product needs written permission from the copyright holder. Tell the user before you
74
- select the preset.
75
-
76
- The `effect` preset needs the `@effect/tsgo` package, which `init` installs at a pinned
77
- version and doctor and `update` keep in sync. Its rules exist only in Oxlint binaries that
78
- `adamantite prepare` patched, so the `prepare` script in `package.json` must run
79
- `adamantite prepare`; without the patch, Oxlint stops with `Unknown plugin: 'effecttsgo'`.
80
- Do not remove the patch or the preset to get past that error: run `adamantite prepare`. If a
81
- production-only install fails at `adamantite prepare`, add `--ignore-scripts` to that
82
- install instead of changing the script. `tsconfig.json` needs
83
- `{ "name": "@effect/language-service", "diagnostics": false }` in `compilerOptions.plugins`,
84
- and `knip.config.ts` needs `ignoreDependencies.effect`. To allow an unstable Effect module
85
- on purpose, add it to `allowedUnstableApis` in that tsconfig entry. Do not turn off
86
- `effecttsgo/unstable-api-usage`. In Effect 4.0.2 and later, the platform modules (such as
87
- `effect/FileSystem` and `effect/Path`), `@effect/platform-node`, and `@effect/vitest` are
88
- unstable. An entry can be a module or a full package.
89
-
90
- The `shadcn` preset needs Tailwind v4 and the `@shadcn/lint` package, which `init` installs
91
- at a pinned version and doctor and `update` keep in sync. The plugin finds components and
92
- the theme through `components.json`. Without that file it looks in `components/ui` or
93
- `src/components/ui` and discovers the stylesheet that imports Tailwind; when components
94
- live elsewhere, set `settings.shadcn` (for example `{ ui: "@/ds" }`) in `oxlint.config.ts`.
95
- The preset turns off the component-owned rules under `**/components/ui/**`; add the same
96
- override for another component directory.
97
-
98
- Adamantite requires TypeScript 7 or later as a dependency in the project's own
99
- `package.json`. Without that entry, npm cannot add or update a managed plugin.
100
-
101
- Only select options supported by the project. Presets and TypeScript require `check` or `fix`;
102
- extension installation requires an editor; `--github-actions` requires a CI-compatible script
103
- and a supported package manager (bun, deno, npm, pnpm, or yarn). Omitted boolean flags are
104
- disabled.
105
-
106
- Existing package scripts whose commands differ from Adamantite's are kept and reported,
107
- not replaced; pass `--overwrite-scripts` to replace them. Custom flags can be forwarded
108
- to the Adamantite command after `--`, e.g. `adamantite analyze -- --directory packages/app`.
109
-
110
- ## Daily workflow
111
-
112
- Use the scripts written by `init` when available. Otherwise invoke the CLI directly:
113
-
114
- ```shell
115
- adamantite check
116
- adamantite fix
117
- adamantite analyze
118
- ```
119
-
120
- - Use `check` for read-only formatting, lint, and type-error validation. `check --only lint` or `check --only format`
121
- runs one stage.
122
- - Use `fix` for automatic Oxlint fixes followed by Oxfmt formatting. Add `--suggested`, `--dangerous`, or `--all` only
123
- with explicit permission after reviewing their impact. `fix --only lint` or `fix --only format` runs one stage.
124
- - Use `analyze` for unused dependencies, exports, and files. In a monorepo it first checks
125
- workspace dependency consistency with Sherif. `analyze --only monorepo` or
126
- `analyze --only unused` runs one stage. `analyze --fix` may remove files, so inspect
127
- findings before using it. Sherif refuses to fix when `CI` is set, so in a monorepo
128
- `analyze --fix` fails there; use `analyze --only unused --fix` for the Knip fixes.
129
- - In a monorepo, `analyze --fix` needs a terminal when Sherif must choose between versions.
130
- Without a terminal, set `"sherif": { "select": "highest" }` in the root `package.json`, or
131
- use `analyze --only unused --fix` to skip Sherif.
132
- - `analyze` runs Sherif without flags. Put Sherif exceptions in the `sherif` field of the root
133
- `package.json` (camelCase CLI options, e.g. `"ignoreDependency": ["tailwindcss"]`).
134
-
135
- To pass arguments to Knip, Oxlint, or Sherif, place them after `--`. For `check` and `fix` they
136
- go to Oxlint. For `analyze` they go to Knip, or to the stage that `--only` selects, so a Sherif
137
- flag needs `--only monorepo`. For a permanent Sherif setting, use the `sherif` field instead.
138
-
139
- ```shell
140
- adamantite check src -- --deny-warnings
141
- bun run analyze -- -- --directory packages/app
142
- adamantite analyze --only monorepo -- --ignore-package package-a
143
- ```
144
-
145
- ## Diagnose and repair
146
-
147
- Run the read-only assessment:
148
-
149
- ```shell
150
- adamantite doctor
151
- ```
152
-
153
- Follow each finding. Doctor supplies the current state, the goal criteria, reference
154
- content when needed, and the verification command. In an interactive terminal, Doctor
155
- offers to hand off to an installed coding agent CLI, or to copy the combined Markdown prompt. In a
156
- non-interactive run — the path an agent uses — Doctor prints Markdown directly. Findings
157
- produce a repair prompt and exit 1. Assessment warnings alone produce a warning report
158
- and exit 0. Run `adamantite doctor` again until it exits 0.
159
-
160
- ## Update
161
-
162
- For an existing installation, run:
163
-
164
- ```shell
165
- adamantite update
166
- adamantite doctor
167
- ```
168
-
169
- `update` updates Adamantite-managed dependencies and, with the effect preset, patches Oxlint
170
- and TypeScript again. It then reports any remaining doctor findings. Follow those findings and review the resulting diff.
22
+ Use Adamantite to maintain the code-quality tools of a target project, the project that
23
+ Adamantite configures or checks.
24
+
25
+ ## Select the task
26
+
27
+ Read the target project's instructions and package scripts. Run commands from its root
28
+ with its package manager and installed Adamantite version. Use `adamantite <command> --help`
29
+ to check options that the task needs.
30
+
31
+ Use the section below that matches the request. Read a linked guide only when that case
32
+ applies. Continue when you have identified the target project, command, and requested scope.
33
+
34
+ ## Set up a target project
35
+
36
+ For a new installation, follow [How to set up Adamantite](references/setup.md).
37
+ Use Doctor for drift in an existing installation. A code-quality failure belongs in the
38
+ checks below, rather than another initialization.
39
+
40
+ Setup is complete when the selected scripts run and Doctor reports no findings.
41
+
42
+ ## Check and fix code
43
+
44
+ Use the project's managed scripts when they exist. Otherwise, run the CLI through the
45
+ project's package manager:
46
+
47
+ - Run `adamantite check` for read-only formatting, lint, and type checks. Fix warnings
48
+ instead of adding `--allow-warnings` to pass the check.
49
+ - Run `adamantite fix` for safe lint fixes and formatting. Review the effect and get explicit
50
+ permission before using `--suggested`, `--dangerous`, or `--all`.
51
+ - Run `adamantite analyze` for unused files, exports, and dependencies. In a monorepo it
52
+ runs Sherif before Knip. Inspect the findings before using `--fix`, which can remove files.
53
+
54
+ To repair preset rule reports or change their configuration, follow
55
+ [How to repair preset rule reports](references/lint-rules.md).
56
+
57
+ Pass underlying tool arguments after `--`. For `check` and `fix`, they go to Oxlint unless
58
+ `--only` selects another stage. For `analyze`, they go to Knip unless `--only` selects
59
+ Sherif. For example, use `adamantite analyze --only monorepo -- --select highest`.
60
+ When a package manager consumes a separator, add another, as in
61
+ `npm run analyze -- -- --directory packages/app`.
62
+
63
+ If Sherif needs a version choice without a terminal, set `sherif.select` to `"highest"`
64
+ in the root `package.json`, or pass `--select highest` to the monorepo stage.
65
+ Keep permanent Sherif settings in that `sherif` object, with camelCase option names.
66
+ Sherif refuses fixes when `CI` is set. Use `analyze --only unused --fix` to run only Knip fixes there.
67
+
68
+ The task is complete when the affected checks exit 0 and you have read their output.
69
+
70
+ ## Repair managed setup
71
+
72
+ Run `adamantite doctor`. It assesses managed integrations without changing files.
73
+ Without a terminal, it prints a Markdown repair prompt and exits 1 when findings remain.
74
+ Follow each finding's current state, goal, reference, and verification command.
75
+ For old layer-map declarations, use the migration step in
76
+ [Configure layer maps and import owners](references/lint-rules.md#configure-layer-maps-and-import-owners).
77
+ For a finding about the previous custom-rules API, use the migration step in
78
+ [How to write and verify custom rules](references/custom-rules.md#repair-an-existing-rules-folder).
79
+
80
+ Run Doctor again after the repair. This step is complete when Doctor exits 0 with no
81
+ findings. Report assessment warnings separately, because warnings alone also exit 0.
82
+
83
+ ## Update managed dependencies
84
+
85
+ Run `adamantite update`. It updates managed dependencies and refreshes stale skill copies
86
+ that `init` installed from the package. It reports remaining setup findings but can exit 0
87
+ with findings still present.
88
+
89
+ Follow the repair step above. The update is complete when Doctor reports no findings and
90
+ the project's checks pass.
91
+
92
+ ## Harden coding standards
93
+
94
+ Run `adamantite harden` and follow its Markdown prompt. Use `--path` to limit the scope
95
+ when the request covers one package or folder. Show the candidate standards and wait for
96
+ the user's approval before writing. If no human can approve, report the candidates and stop.
97
+
98
+ For rule trials that the prompt requests, follow the trial step in
99
+ [How to repair preset rule reports](references/lint-rules.md#try-a-rule-setting).
100
+ For approved custom rules, follow [How to write and verify custom rules](references/custom-rules.md).
101
+
102
+ A non-interactive `harden` run only prints the prompt. Its exit code does not verify the
103
+ work. Hardening is complete when the approved standards are enforced, the checks pass,
104
+ and Doctor reports no findings.
171
105
 
172
106
  ## Custom rules
173
107
 
174
- <!-- Keep this section the same as the AGENTS.md text in src/lib/workspace/custom-rules.ts. -->
175
-
176
- Each file in the rules folder, `.adamantite/rules/` by default, is an Oxlint rule that this
177
- project owns. `custom()` from `adamantite/lint/custom` loads the folder and enables each
178
- rule as `error` under the `project` plugin: `no-process-env.ts` becomes
179
- `project/no-process-env`. Add a file to add a rule. Delete the file to remove the rule.
180
- `adamantite rule add <name>` writes a correct stub.
181
-
182
- - A file that starts with `_`, such as `_helpers.ts`, is a helper, not a rule. Subfolders are
183
- not read.
184
- - Export the rule as default with `defineRule` from `adamantite/rules`. The same module exports
185
- the `Context`, `Rule`, `Visitor`, and `ESTree` node types.
186
- - Use `createOnce`. It runs one time for each lint run, not one time for each file. Reset
187
- per-file state in `before`, and report collected results in `after`. `context.filename`,
188
- `context.sourceCode`, and `context.settings` are not available in the body of
189
- `createOnce`. Read them in `before` or in a visitor.
190
- - Write erasable TypeScript only. Oxlint loads rule files with Node.js type stripping, so
191
- `enum`, a `namespace` with values, parameter properties, and `import x = require()` stop
192
- the lint run.
193
- - Rules get no type information. Use only the AST and `context.sourceCode`.
194
- - Report with a `messageId`, and put each message in `meta.messages`. Describe the options in
195
- `meta.schema`, and read them from `context.options`.
196
- - A rule that throws prints an error for each file, and the lint run still exits 0. After you
197
- change a rule, run the lint and read all of its output.
198
- - To find node names, run `adamantite rule ast <file>` on real code. It prints the same
199
- ESTree-shaped AST that rules visit.
200
- - To test a rule, use `RuleTester` from `oxlint/plugins-dev`. Adamantite does not run rule
201
- tests.
202
- - Oxlint caches the rules for each run. Restart the editor language server after you change a
203
- rule.
204
- - TypeScript does not check `.adamantite/rules/` by default, because its name starts with a dot. Add
205
- `".adamantite/rules"` to `include` in `tsconfig.json` to check it.
206
- - In a monorepo, give each rules folder its own plugin name, such as `custom({ name: "web" })`:
207
- Oxlint rejects two plugins with the same name in one run. A relative `dir` resolves from the
208
- file that calls `custom()`, so a shared tooling package can own the rules with
209
- `custom({ dir: "rules", name: "acme" })`. A nested Oxlint config replaces the root config, so
210
- a package that needs the root rules extends the root config.
211
-
212
- ## Decision guide
213
-
214
- - New target project: `init`, then run the configured checks.
215
- - Suspected drift or broken setup: run `doctor` and follow its findings.
216
- - Existing project upgrading Adamantite: `update`, then the doctor sequence.
217
- - Code-quality failure: choose `check` or `analyze` based on the failing subsystem; do not
218
- reinitialize the project.
219
- - Project-specific lint rule: add a custom rule with `adamantite rule add <name>`; do not
220
- edit Adamantite presets.
221
- - Unknown option or behavior: run `adamantite <command> --help` before guessing.
108
+ To add, change, verify, or save tests for a project-owned rule, follow
109
+ [How to write and verify custom rules](references/custom-rules.md).
110
+
111
+ The task is complete when the guide's verification and cleanup checks pass.
112
+
113
+ ## Report the result
114
+
115
+ If a required tool or source was unavailable, name it on the first line and state what you
116
+ used instead. Report the changes, commands run, results, and remaining findings or warnings.
117
+ For a custom rule, include the cases tested and whether you removed temporary verification files.
118
+
119
+ The report is complete when every result has command output or an inspected artifact as evidence.
120
+
121
+ ## Check the result
122
+
123
+ - The selected command matches the requested task and scope.
124
+ - The affected checks passed, or the report names the checks that remain unverified.
125
+ - Doctor findings and assessment warnings are reported separately.
126
+ - Every new or changed custom rule passed verification, and temporary cases are removed.
@@ -0,0 +1,120 @@
1
+ # How to write and verify custom rules
2
+
3
+ ## Select the rules folder
4
+
5
+ Use a custom rule for a recurring project coding standard that existing rules cannot check.
6
+ Keep it in the target project. A first-party preset change is a different task.
7
+
8
+ Find the `custom()` call imported from `adamantite/rules` in the project's Oxlint configuration.
9
+ It loads `.adamantite/lint` by default, relative to the file that calls it, and enables each
10
+ rule as `error` under `project`. Thus `no-process-env.ts` becomes `project/no-process-env`.
11
+ Use `dir` for another folder. In a monorepo, give each rules folder its own plugin `name`,
12
+ because Oxlint rejects duplicate plugin names in one run. A nested Oxlint config replaces
13
+ the root config. Extend the root config when the package needs its rules.
14
+
15
+ Continue when you have identified the loaded rules folder and its plugin name.
16
+
17
+ ## Repair an existing rules folder
18
+
19
+ If Doctor reports the previous API, replace `adamantite/lint/custom` with the default import
20
+ from `adamantite/rules`. Move authoring imports to `adamantite/rules/plugin`.
21
+ Move the old default folder to `.adamantite/lint`, or set its path with `dir`.
22
+ Preserve rule behavior, plugin names, severity, and options.
23
+
24
+ Continue when Doctor reports no custom-rule wiring findings.
25
+
26
+ ## Write the rule
27
+
28
+ For a new rule, run `adamantite rule add <name>`. It writes only a stub.
29
+ Use `adamantite rule ast <file>` on real code to find the node types that visitors receive.
30
+
31
+ Apply these authoring constraints:
32
+
33
+ - Export the rule as default with `defineRule` from `adamantite/rules/plugin`.
34
+ Import `Context`, `Rule`, `Visitor`, and `ESTree` types from that module when needed.
35
+ - Use `createOnce`, which runs once for the lint run. Reset per-file state in `before` and
36
+ report collected results in `after`. Read `context.filename`, `context.sourceCode`, and
37
+ `context.settings` in `before` or a visitor. They are unavailable in the `createOnce` body.
38
+ - Write erasable TypeScript. Replace an `enum` with a plain object, for example.
39
+ Node.js type stripping cannot load enums, namespaces with values, parameter properties,
40
+ or `import x = require()`.
41
+ - Use the AST and `context.sourceCode`. Custom rules receive no type information.
42
+ - Report with a `messageId` defined in `meta.messages`. State what the author must do
43
+ instead and link the coding standard. Define options in `meta.schema` and read `context.options`.
44
+ - Keep substantial logic in plain functions in a `_<name>.ts` helper when that makes the
45
+ rule clearer. Files that start with `_`, declaration files, and `.test.*` files are not rules.
46
+ Subfolders are not loaded.
47
+
48
+ Continue when the rule implements the standard and every report gives a repair.
49
+
50
+ ## Verify the rule
51
+
52
+ Use `RuleTester` from `adamantite/rules/testing` with Node.js, also in a Bun project.
53
+ Put code that must report in `invalid` and similar code that must pass in `valid`.
54
+ Cover the syntax forms and file paths to which the standard applies.
55
+ For a bug fix, first run a regression case and confirm that it fails. Fix the rule and rerun
56
+ all cases. Change a case only when it is wrong, and explain the change.
57
+
58
+ Run temporary cases from stdin or a temporary file beside the rule. For the generated
59
+ `no-debugger` stub, this command checks the report and an accepted TypeScript declaration:
60
+
61
+ ```sh
62
+ node --input-type=module <<'JS'
63
+ import { RuleTester } from "adamantite/rules/testing"
64
+ import rule from "./.adamantite/lint/no-debugger.ts"
65
+
66
+ new RuleTester({ languageOptions: { parserOptions: { lang: "ts" } } }).run("no-debugger", rule, {
67
+ invalid: [{ code: "debugger", errors: [{ messageId: "unexpected" }] }],
68
+ valid: ["const value: number = 1"],
69
+ })
70
+ JS
71
+ ```
72
+
73
+ Adapt the cases to the completed rule. Verify a helper directly only when its cases are too
74
+ many for RuleTester. During harden, use `adamantite rule test add <name>` to prepare temporary
75
+ cases, adapt them, and run `adamantite rule test --path <test-file>`.
76
+ If a saved test already exists, preserve it and use stdin for additional temporary cases.
77
+
78
+ Run lint and read all output. A rule that throws can print an error for every file while
79
+ Oxlint still exits 0. Restart the editor language server after changing a rule, because
80
+ Oxlint caches rules for each run.
81
+
82
+ Continue when every valid and invalid case passes and lint output contains no rule errors.
83
+
84
+ ## Keep saved tests when requested
85
+
86
+ If the user requests new saved tests, run `adamantite rule test add <name>` and adapt its
87
+ valid and invalid cases. Use `--dir` for another rules folder or `--path` for another test location.
88
+ Keep `.test.ts` for tests beside rules, so the plugin does not load them as rules.
89
+ Run saved tests with `adamantite rule test`, or `adamantite rule test --path <file>` for a test elsewhere.
90
+
91
+ Saved tests use `node:test`. Exclude them from Vitest `test.exclude` or Jest
92
+ `testPathIgnorePatterns`, while keeping the runner's default and existing exclusions.
93
+ Init, CI generation, and harden do not run saved tests by default. Preserve existing test
94
+ files and CI steps. Add new CI test steps only when requested.
95
+
96
+ Continue when the saved tests pass and the project's other test runners do not collect them.
97
+
98
+ ## Check project integration
99
+
100
+ If TypeScript must check the rules folder, add `.adamantite/lint` to tsconfig `include`.
101
+ TypeScript skips the dot folder by default. Enable `allowImportingTsExtensions` when checking
102
+ tests that import `.ts` rule files.
103
+
104
+ Knip treats rules and optional `.test.*` files in `.adamantite/lint` as entry files in the
105
+ root and workspace packages. For another folder, keep the preset's entry patterns and add
106
+ the folder's rule and test patterns to `oxlint.entry` in `knip.config.ts`.
107
+ Add tests saved elsewhere to the Knip entry settings if needed.
108
+
109
+ Remove temporary cases, fixtures, and verification-only helpers that you created.
110
+ Keep the rule, its runtime helpers, required configuration, and user-owned saved tests.
111
+ Run `adamantite check` and `adamantite doctor`.
112
+
113
+ Continue when both commands pass and no temporary verification files remain.
114
+
115
+ ## Check the rule
116
+
117
+ - Every valid and invalid case passes, including the regression case for a bug fix.
118
+ - Lint output contains no rule errors, regardless of its exit code.
119
+ - Doctor reports no findings, and the project's checks pass.
120
+ - Temporary verification files are removed, and user-owned tests and CI steps remain.
@@ -0,0 +1,158 @@
1
+ # How to repair preset rule reports
2
+
3
+ ## Repair the reported code
4
+
5
+ Read the rule message and apply the section below that matches it.
6
+
7
+ - For `adamantite/no-react-state-hooks`, follow the message's replacement for the hook.
8
+ Moving the call into a hook module only to silence the report leaves the problem in place.
9
+ Set `allow` only when the project's hook layout differs from the default.
10
+ - For `adamantite/no-overzealous-destructuring`, keep the object and read its members, or split
11
+ the pattern. Raising `maxDepth` or `maxProperties` only to pass the check hides the problem.
12
+ - For `adamantite/require-suppression-reason`, first try to fix the code. If a suppression is
13
+ necessary, state why the rule does not apply after `--`. Naming the rule or adding a single
14
+ `-` gives no reason. For example, use
15
+ `// oxlint-disable-next-line no-console -- the CLI writes its report to stdout`.
16
+ - For `no-warning-comments`, fix the code or track the work in the project's issue tracker.
17
+ Renaming `TODO` to another marker only to pass the check leaves the work untracked.
18
+ - For `adamantite/query-from-loader` reports on `useQuery` or `useSuspenseQuery`, replace a
19
+ plain options object or a local `queryOptions()` call with shared options. Define them with
20
+ `queryOptions()` at module scope or in an exported factory. Preload them with
21
+ `ensureQueryData()` in the loader and pass the same options to the hook. For reports on
22
+ `useInfiniteQuery` or `useSuspenseInfiniteQuery`, use `infiniteQueryOptions()` with
23
+ `ensureInfiniteQueryData()`. Wrapping options in a spread or moving the hook out of the route
24
+ only to silence the report leaves the preload problem unresolved.
25
+ - For `adamantite/no-query-data-in-state`, read query data from the query result and keep
26
+ only the user's edits in state.
27
+ - For `effecttsgo/unstable-api-usage`, add a deliberately accepted module or package to
28
+ `allowedUnstableApis` in the `@effect/language-service` tsconfig entry. For example, list
29
+ `"effect/cli"` to allow that module instead of disabling the rule for every unstable API.
30
+
31
+ Continue when the reported code follows the rule's repair and the affected lint check passes.
32
+
33
+ ## Configure layer maps and import owners
34
+
35
+ If the task changes import rules, use the first-party plugin loaded by `architecture` or
36
+ `strict`. The `architecture` preset enables no rules until the project configures them.
37
+
38
+ Set `adamantite/layers` with a layer map. Give each layer an `imports` list of sibling
39
+ layers. Imports are transitive. Put a child map in the containing layer's `layers` property:
40
+
41
+ ```ts
42
+ import architecture from "adamantite/lint/architecture"
43
+ import { defineConfig } from "oxlint"
44
+
45
+ export default defineConfig({
46
+ extends: [architecture],
47
+ rules: {
48
+ "adamantite/layers": [
49
+ "error",
50
+ {
51
+ root: "src",
52
+ layers: {
53
+ lib: {
54
+ imports: [],
55
+ layers: {
56
+ shared: { imports: [] },
57
+ services: { imports: ["shared"] },
58
+ },
59
+ },
60
+ terminal: { imports: ["lib"] },
61
+ commands: { imports: ["terminal"] },
62
+ },
63
+ },
64
+ ],
65
+ },
66
+ })
67
+ ```
68
+
69
+ Resolve `root` from the nearest `package.json` folder. The `lib` child map has the root
70
+ `src/lib`, and its dependency names are local to that map. Every containing map checks a
71
+ file independently. A child permission cannot override a parent prohibition. Declaration
72
+ order does not change permissions.
73
+
74
+ Use `entries` for composition files, `isolate` for layers whose child folders cannot import
75
+ each other, and `ignoreTypes` when type-only imports do not count. Add import `conditions`
76
+ explicitly when resolution needs them. The rule does not read tsconfig `customConditions`.
77
+ An unresolved import is not checked. A folder missing from the map is reported. Move a
78
+ loose root file into a layer or declare it as an entry.
79
+
80
+ Place child settings beside the child's `layers`. Settings do not inherit. A parent's
81
+ `ignore`, `entries`, or `ignoreTypes` does not skip child checks. A child root uses the
82
+ parent's actual matched folder, including when the top root is a glob. Declare each
83
+ concrete scope once. Keep separate option objects for roots that cannot nest without a
84
+ new intermediate map.
85
+
86
+ If the config uses the previous array-valued declarations, run `adamantite doctor` and
87
+ follow its migration instructions. Preserve every dependency and map setting. Nest only
88
+ existing compatible child scopes. Verify allowed and forbidden imports with
89
+ `adamantite check`, then run Doctor again. Continue when the migrated maps preserve the
90
+ project's intended imports and Doctor reports no layer-map migration finding.
91
+
92
+ For an import that belongs to one file or folder, set `adamantite/import-owners`:
93
+
94
+ ```ts
95
+ import architecture from "adamantite/lint/architecture"
96
+ import { defineConfig } from "oxlint"
97
+
98
+ export default defineConfig({
99
+ extends: [architecture],
100
+ rules: {
101
+ "adamantite/import-owners": [
102
+ "error",
103
+ { import: "giget", owners: ["src/services/download.ts"] },
104
+ { import: "react-native", names: ["Alert"], owners: ["src/shared/alerts.ts"] },
105
+ { import: "#lib/database.ts", owners: ["src/lib/repositories"] },
106
+ ],
107
+ },
108
+ })
109
+ ```
110
+
111
+ Resolve owners from the workspace root, or the `package.json` folder outside a workspace.
112
+ An owner folder covers every file below it. A package name covers its subpaths.
113
+ Use `names` to restrict selected exports. Namespace imports and `export *` are also reported
114
+ when names are restricted. An `import` that starts with `#`, `.`, or `/` names a file or folder of
115
+ the project, resolved from the same root as the owners. The rule resolves each import of a linted
116
+ file, so a relative path or another alias to that module counts too. An import that names a `#`
117
+ module as the option states it also counts, as for a package. In a monorepo, a `#` option restricts
118
+ that alias in every package. To restrict a folder of one package, name its path from the workspace
119
+ root, such as `./apps/web/src/lib/db`. Use layer maps for the dependencies between folders.
120
+
121
+ Repair a report by using what the owner exports or moving the code to its layer or owner.
122
+ Adding an owner, layer dependency, or `ignore` glob only to pass the check weakens the standard.
123
+ Continue when the configured maps and owners match the project's intended imports.
124
+
125
+ ## Change test rule configuration
126
+
127
+ If a Jest or Vitest preset needs different test paths or rule settings, replace its entry in
128
+ `extends` with a project override. Use the preset's exported `testFiles`, or the project's
129
+ test paths, with its `plugins` and `rules`. For example:
130
+
131
+ ```ts
132
+ import vitest, { testFiles } from "adamantite/lint/vitest"
133
+ import { defineConfig } from "oxlint"
134
+
135
+ export default defineConfig({
136
+ overrides: [{ files: testFiles, plugins: vitest.plugins, rules: { ...vitest.rules } }],
137
+ })
138
+ ```
139
+
140
+ Change test rules in that override. Top-level rules do not replace the preset's test override.
141
+ Keep `plugins` in it, because Oxlint ignores `vitest/*` rules without the plugin.
142
+ Continue when the intended test files receive the configured rules.
143
+
144
+ ## Try a rule setting
145
+
146
+ Before changing a rule setting, run `adamantite rule try <rule> --report <case> --accept <case>`
147
+ when the task requires evidence from cases. Use `--options '<json array>'` for options after
148
+ the severity, or `--current` for the setting in the config. A case is a project path, or
149
+ `<path>=<file>` to lint the content of `<file>` at `<path>` in a copy of the project.
150
+
151
+ Continue when every case gives the expected result. Exit code 1 means a case differs.
152
+ Exit code 2 means the trial could not supply evidence, such as when the rule does not exist.
153
+
154
+ ## Check the repair
155
+
156
+ - The changed code or configuration follows the project's coding standard.
157
+ - The affected lint check passes without a broader exception added only to silence it.
158
+ - Each requested trial ran successfully and gave the expected results.