adamantite 0.45.0 → 0.46.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +368 -122
- package/dist/index.js +638 -57
- package/dist/oxlint.js +1 -0
- package/dist/presets/analyze.js +1 -0
- package/dist/presets/lint/{react-doctor.d.ts → architecture.d.ts} +1 -1
- package/dist/presets/lint/architecture.js +8 -0
- package/dist/presets/lint/core.js +0 -1
- package/dist/presets/lint/effect.js +26 -1
- package/dist/presets/lint/plugin/glob.d.ts +7 -0
- package/dist/presets/lint/plugin/glob.js +48 -0
- package/dist/presets/lint/plugin/imports.d.ts +4 -0
- package/dist/presets/lint/plugin/imports.js +4 -1
- package/dist/presets/lint/plugin/index.d.ts +3 -0
- package/dist/presets/lint/plugin/index.js +14 -8
- package/dist/presets/lint/plugin/options.d.ts +5 -5
- package/dist/presets/lint/plugin/options.js +19 -7
- package/dist/presets/lint/plugin/resolver.d.ts +8 -0
- package/dist/presets/lint/plugin/resolver.js +79 -0
- package/dist/presets/lint/plugin/rules/import-owners.d.ts +67 -0
- package/dist/presets/lint/plugin/rules/import-owners.js +310 -0
- package/dist/presets/lint/plugin/rules/layers.d.ts +136 -0
- package/dist/presets/lint/plugin/rules/layers.js +479 -0
- package/dist/presets/lint/plugin/rules/no-query-data-in-state.js +1 -1
- package/dist/presets/lint/plugin/rules/no-react-state-hooks.d.ts +0 -5
- package/dist/presets/lint/plugin/rules/no-react-state-hooks.js +3 -47
- package/dist/presets/lint/plugin/rules/query-from-loader.js +2 -2
- package/dist/presets/lint/plugin/rules/require-suppression-reason.d.ts +5 -0
- package/dist/presets/lint/plugin/rules/require-suppression-reason.js +32 -0
- package/dist/presets/lint/react-strict.js +22 -2
- package/dist/presets/lint/strict.js +35 -2
- package/dist/presets/lint/{antislop.d.ts → tailwind.d.ts} +1 -1
- package/dist/presets/lint/{shadcn.js → tailwind.js} +1 -1
- package/dist/presets/lint/vendor/antislop/license.md +26 -1
- package/dist/presets/lint/vendor/antislop/plugin.d.mts +3 -0
- package/dist/presets/lint/vendor/antislop/plugin.mjs +940 -31
- package/dist/presets/lint/vendor/antislop-effect/license.md +27 -0
- package/dist/presets/lint/vendor/antislop-effect/plugin.d.mts +17 -0
- package/dist/presets/lint/vendor/antislop-effect/plugin.mjs +579 -0
- package/dist/presets/{lint → rules}/custom.d.ts +3 -20
- package/dist/presets/{lint → rules}/custom.js +50 -46
- package/dist/presets/rules/folder.d.ts +34 -0
- package/dist/presets/rules/folder.js +52 -0
- package/dist/presets/rules/index.d.ts +2 -9
- package/dist/presets/rules/index.js +1 -29
- package/dist/presets/rules/load.d.ts +8 -0
- package/dist/presets/rules/load.js +29 -0
- package/dist/presets/rules/plugin.d.ts +3 -0
- package/dist/presets/rules/plugin.js +1 -0
- package/dist/presets/rules/testing.d.ts +2 -0
- package/dist/presets/rules/testing.js +14 -0
- package/dist/presets/tsconfig.json +3 -0
- package/dist/runtime-CVZPDpfE.js +11 -0
- package/package.json +79 -18
- package/skills/adamantite/SKILL.md +112 -207
- package/skills/adamantite/references/custom-rules.md +120 -0
- package/skills/adamantite/references/lint-rules.md +158 -0
- package/skills/adamantite/references/setup.md +64 -0
- package/dist/presets/lint/antislop.js +0 -28
- package/dist/presets/lint/react-doctor.js +0 -20
- package/dist/presets/lint/shadcn.d.ts +0 -5
|
@@ -1,221 +1,126 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: adamantite
|
|
3
|
-
description:
|
|
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.
|
|
7
|
+
library_version: "0.45.0"
|
|
8
8
|
sources:
|
|
9
9
|
- "adelrodriguez/adamantite:src/cli.ts"
|
|
10
|
-
- "adelrodriguez/adamantite:src/commands
|
|
11
|
-
- "adelrodriguez/adamantite:src/lib/
|
|
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
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
##
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
`
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
`adamantite
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
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
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
-
|
|
191
|
-
|
|
192
|
-
|
|
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.
|