@antelopejs/tooling-configs 0.0.8 → 0.0.9
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 +80 -126
- package/package.json +8 -2
package/README.md
CHANGED
|
@@ -1,41 +1,48 @@
|
|
|
1
1
|
# @antelopejs/tooling-configs
|
|
2
2
|
|
|
3
3
|
<div align="center">
|
|
4
|
-
<a href="https://www.npmjs.com/package/@antelopejs/tooling-configs"><img alt="
|
|
5
|
-
<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/tooling-configs
|
|
4
|
+
<a href="https://www.npmjs.com/package/@antelopejs/tooling-configs"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/tooling-configs?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
5
|
+
<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/tooling-configs?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
6
6
|
<a href="https://discord.gg/sjK28QHrA7"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000" alt="Discord"></a>
|
|
7
|
-
<a href="https://antelopejs.com"><img src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000" alt="Documentation"></a>
|
|
8
7
|
</div>
|
|
9
8
|
|
|
10
|
-
Shared
|
|
11
|
-
the vendored [anti-slop](https://github.com/dmmulroy/anti-slop) rules), [oxfmt](https://oxc.rs)
|
|
12
|
-
and [Knip](https://knip.dev).
|
|
9
|
+
Shared lint, format and dead-code presets for AntelopeJS repositories, plus a check for the version ranges of interface dependencies.
|
|
13
10
|
|
|
14
|
-
|
|
15
|
-
Nuxt
|
|
16
|
-
|
|
11
|
+
- [oxlint](https://oxc.rs) and [oxfmt](https://oxc.rs) replace Biome: lint, format and Tailwind class sorting, `.vue` included.
|
|
12
|
+
- ESLint stays for the Nuxt front ends, from a shared config, until oxlint lints `.vue` files.
|
|
13
|
+
- [Knip](https://knip.dev) learns the entry points of an AntelopeJS module.
|
|
14
|
+
- Every preset is a function: options adjust it without copying it.
|
|
17
15
|
|
|
18
|
-
##
|
|
16
|
+
## What's in the box
|
|
19
17
|
|
|
20
|
-
|
|
21
|
-
|
|
18
|
+
| Export | Import | What it gives |
|
|
19
|
+
| ----------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------- |
|
|
20
|
+
| `./oxc/lint` | `import { antelopePreset } from "@antelopejs/tooling-configs/oxc/lint"` | The oxlint preset |
|
|
21
|
+
| `./oxc/fmt` | `import { antelopeFmtPreset } from "@antelopejs/tooling-configs/oxc/fmt"` | The oxfmt preset (house style) |
|
|
22
|
+
| `./eslint` | `import { antelopeNuxtConfig } from "@antelopejs/tooling-configs/eslint"` | ESLint for Nuxt layers |
|
|
23
|
+
| `./knip` | `import { antelopeKnipConfig } from "@antelopejs/tooling-configs/knip"` | Knip for AntelopeJS modules |
|
|
24
|
+
| `./oxc/anti-slop` | Loaded by the oxlint preset as a JS plugin | The vendored [anti-slop](https://github.com/dmmulroy/anti-slop) rules |
|
|
25
|
+
| bin | `antelopejs-check-interface-ranges` | Fails on interface ranges that break module startup |
|
|
22
26
|
|
|
23
27
|
## Install
|
|
24
28
|
|
|
29
|
+
Node.js 24, or at least 22.18: oxlint reads `oxlint.config.ts` and loads JS plugins by executing TypeScript.
|
|
30
|
+
|
|
25
31
|
```bash
|
|
26
|
-
pnpm add -D oxlint@1.81.0 oxfmt
|
|
32
|
+
pnpm add -D @antelopejs/tooling-configs oxlint@1.81.0 oxfmt
|
|
27
33
|
```
|
|
28
34
|
|
|
29
|
-
|
|
30
|
-
optional peer dependency because it pulls ESLint and typescript-eslint along with it:
|
|
35
|
+
The tools are optional peer dependencies, so add only the ones a repository uses:
|
|
31
36
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
37
|
+
| Tool | Packages to add |
|
|
38
|
+
| ----------------------- | -------------------------------------------------------------------------------- |
|
|
39
|
+
| oxlint | `oxlint@1.81.0`, plus `oxlint-tsgolint` for the type-aware rules (on by default) |
|
|
40
|
+
| oxfmt | `oxfmt@^0.66.0` |
|
|
41
|
+
| ESLint | `@nuxt/eslint-config` |
|
|
42
|
+
| Knip | `knip@>=6` |
|
|
43
|
+
| Import sorting (opt-in) | `eslint-plugin-perfectionist` |
|
|
35
44
|
|
|
36
|
-
Pin `oxlint` to the exact version this package
|
|
37
|
-
(currently **1.81.0**). The JS plugin API is still alpha and the two packages must move
|
|
38
|
-
together.
|
|
45
|
+
Pin `oxlint` to the exact version this package uses for `@oxlint/plugins` (currently **1.81.0**): the JS plugin API is still alpha and the two must move together.
|
|
39
46
|
|
|
40
47
|
## oxlint
|
|
41
48
|
|
|
@@ -46,7 +53,7 @@ import { antelopePreset } from "@antelopejs/tooling-configs/oxc/lint";
|
|
|
46
53
|
|
|
47
54
|
export default defineConfig({
|
|
48
55
|
extends: [antelopePreset()],
|
|
49
|
-
//
|
|
56
|
+
// oxlint reads this field only from the root config, never from a preset.
|
|
50
57
|
options: { typeAware: true },
|
|
51
58
|
});
|
|
52
59
|
```
|
|
@@ -61,23 +68,20 @@ export default defineConfig({
|
|
|
61
68
|
}
|
|
62
69
|
```
|
|
63
70
|
|
|
64
|
-
|
|
71
|
+
### What the preset turns on
|
|
65
72
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
73
|
+
| Group | Rules | Default |
|
|
74
|
+
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
|
75
|
+
| oxc | the `correctness` category, with the `eslint`, `typescript`, `node`, `oxc`, `import` and `promise` plugins; `no-unused-vars` (`_` prefix allowed), `eqeqeq` (`== null` allowed), `radix`, `prefer-regex-literals` | error |
|
|
76
|
+
| Imports | `import/no-cycle`, `import/no-self-import`, `import/no-duplicates` | error |
|
|
77
|
+
| Type-aware | `typescript/no-floating-promises` as an error, eight more type-aware rules as warnings | on |
|
|
78
|
+
| Complexity | `max-params` 5, `max-lines-per-function` 120, `max-lines` 500, `max-depth` 4, `complexity` 20 | warn |
|
|
79
|
+
| Anti-slop | 7 of the 15 vendored rules; the 8 others are listed in `ANTI_SLOP_RULES_OFF_BY_DEFAULT` | warn |
|
|
80
|
+
| Import sorting | `perfectionist/sort-imports`, autofixed by `oxlint --fix` | off |
|
|
69
81
|
|
|
70
|
-
|
|
82
|
+
`correctness` is raised to error on purpose: oxlint reports it as warnings, and warnings never fail the command. Complexity and anti-slop start as warnings so a repository can work through its backlog before raising them to `"error"`.
|
|
71
83
|
|
|
72
|
-
|
|
73
|
-
| -------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
74
|
-
| oxc defaults | the `correctness` category, plus the `eslint`, `typescript`, `node`, `oxc`, `import` and `promise` plugins |
|
|
75
|
-
| imports | `import/no-cycle`, `import/no-self-import`, `import/no-duplicates` as errors |
|
|
76
|
-
| | (a repository with existing cycles starts with `importCycles: "warn"`) |
|
|
77
|
-
| import sorting | `perfectionist/sort-imports`, autofixed by `oxlint --fix` |
|
|
78
|
-
| complexity | `max-params` 5, `max-lines-per-function` 120, `max-lines` 500, `max-depth` 4, `complexity` 20 — as warnings |
|
|
79
|
-
| anti-slop | all 15 generic rules, as warnings |
|
|
80
|
-
| type-aware | `typescript/no-floating-promises` as an error |
|
|
84
|
+
Import sorting is off because it moves value imports across side-effect imports, and in an AntelopeJS module `import "./components"` is what registers the decorated classes. Turn it on only where import order does not matter.
|
|
81
85
|
|
|
82
86
|
### Options
|
|
83
87
|
|
|
@@ -85,26 +89,19 @@ pnpm add -D oxlint-tsgolint
|
|
|
85
89
|
antelopePreset({
|
|
86
90
|
antiSlop: "error", // "warn" (default) | "error" | false
|
|
87
91
|
importCycles: "warn", // "error" (default) | "warn" | false
|
|
88
|
-
complexity: { maxParams: 8 }, // override thresholds, or false
|
|
89
|
-
importSorting:
|
|
90
|
-
typeAware: false, //
|
|
92
|
+
complexity: { maxParams: 8 }, // override thresholds or severity, or false
|
|
93
|
+
importSorting: true, // false (default); needs eslint-plugin-perfectionist
|
|
94
|
+
typeAware: false, // true (default); false when the repository has no oxlint-tsgolint
|
|
91
95
|
});
|
|
92
96
|
```
|
|
93
97
|
|
|
94
|
-
|
|
95
|
-
do not fail the command — a preset that left it alone could never fail a pipeline, while
|
|
96
|
-
Biome was failing the build on the same rules.
|
|
98
|
+
### Add ignore patterns
|
|
97
99
|
|
|
98
|
-
`
|
|
99
|
-
has findings to work through, and a red pipeline on day one teaches the team to ignore
|
|
100
|
-
the pipeline. Raise them to `"error"` once the backlog is clear.
|
|
101
|
-
|
|
102
|
-
### Adding your own ignore patterns
|
|
103
|
-
|
|
104
|
-
oxlint does not merge `ignorePatterns` across `extends`. A root config that declares its
|
|
105
|
-
own **replaces** the preset's, so spread them:
|
|
100
|
+
oxlint does not merge `ignorePatterns` across `extends`: a root config that declares its own replaces the preset's. Spread the shared ones:
|
|
106
101
|
|
|
107
102
|
```ts
|
|
103
|
+
// oxlint.config.ts
|
|
104
|
+
import { defineConfig } from "oxlint";
|
|
108
105
|
import {
|
|
109
106
|
ANTELOPE_IGNORE_PATTERNS,
|
|
110
107
|
antelopePreset,
|
|
@@ -135,55 +132,23 @@ export default antelopeFmtPreset();
|
|
|
135
132
|
}
|
|
136
133
|
```
|
|
137
134
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
| Option | Value |
|
|
141
|
-
| ---------------------- | ---------- |
|
|
142
|
-
| `printWidth` | 80 |
|
|
143
|
-
| `tabWidth` / `useTabs` | 2 / spaces |
|
|
144
|
-
| `semi` | true |
|
|
145
|
-
| `singleQuote` | false |
|
|
146
|
-
| `trailingComma` | `"all"` |
|
|
147
|
-
|
|
148
|
-
Every field is set explicitly, including those that already match oxfmt's defaults.
|
|
149
|
-
Repositories carry `.editorconfig` files that contradict each other — five declare tabs,
|
|
150
|
-
two declare spaces, which is why the codebases drifted apart in the first place — and
|
|
151
|
-
oxfmt falls back to `.editorconfig` for any field a config leaves unset. Stating all of
|
|
152
|
-
them is what makes the style identical everywhere. Fix the repository's `.editorconfig`
|
|
153
|
-
to match anyway, so editors agree with the formatter.
|
|
154
|
-
|
|
155
|
-
Import order is not part of it: `perfectionist/sort-imports` owns that on the lint side.
|
|
156
|
-
Enabling oxfmt's `sortImports` as well would have two tools sorting the same imports
|
|
157
|
-
differently, each undoing the other on every save.
|
|
135
|
+
The house style sets every field, so `.editorconfig` files cannot override it: `printWidth` 80, 2 spaces, semicolons, double quotes, `trailingComma: "all"`. Fix the repository's `.editorconfig` to match anyway, so editors agree with the formatter.
|
|
158
136
|
|
|
159
|
-
The preset
|
|
160
|
-
the release commit lands unformatted, so checking it would turn the default branch red
|
|
161
|
-
after every release with a breaking change.
|
|
162
|
-
|
|
163
|
-
Extra ignores are **added** to the shared ones rather than replacing them, so a repository
|
|
164
|
-
adopting oxfmt in stages can park a directory without losing the rest:
|
|
165
|
-
|
|
166
|
-
```ts
|
|
167
|
-
export default antelopeFmtPreset({ ignorePatterns: ["frontend-vue/**"] });
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
In a front end, pass the theme stylesheet to replace `prettier-plugin-tailwindcss`:
|
|
137
|
+
The preset leaves import order to the linter and ignores `CHANGELOG.md`, which changelogen writes unformatted on every release. Other options of oxfmt pass through. Two are specific:
|
|
171
138
|
|
|
172
139
|
```ts
|
|
140
|
+
// oxfmt.config.ts
|
|
173
141
|
export default antelopeFmtPreset({
|
|
174
|
-
|
|
142
|
+
ignorePatterns: ["frontend-vue/**"], // added to the shared ignores, not replacing them
|
|
143
|
+
tailwindStylesheet: "./assets/css/main.css", // sorts Tailwind classes, replacing prettier-plugin-tailwindcss
|
|
175
144
|
});
|
|
176
145
|
```
|
|
177
146
|
|
|
178
|
-
###
|
|
147
|
+
### Replace Biome
|
|
179
148
|
|
|
180
|
-
|
|
181
|
-
`lint:fix` and `format` at oxlint and oxfmt, and port anything the Biome config carried
|
|
182
|
-
that the preset does not (`noRestrictedImports` guards become `import/no-cycle`). Reformat
|
|
183
|
-
in its own commit and record it in `.git-blame-ignore-revs`, which GitHub honours, so the
|
|
184
|
-
pass does not bury the history.
|
|
149
|
+
Delete `biome.json` and the `@biomejs/biome` dependency, point `lint`, `lint:fix` and `format` at oxlint and oxfmt, and port what the Biome config carried that the preset does not. Reformat in its own commit and list it in `.git-blame-ignore-revs`, which GitHub honours.
|
|
185
150
|
|
|
186
|
-
## ESLint (front ends)
|
|
151
|
+
## ESLint (Nuxt front ends)
|
|
187
152
|
|
|
188
153
|
oxlint does not lint `.vue` files yet, so the front end stays on ESLint:
|
|
189
154
|
|
|
@@ -194,15 +159,7 @@ import { antelopeNuxtConfig } from "@antelopejs/tooling-configs/eslint";
|
|
|
194
159
|
export default antelopeNuxtConfig({ dirs: ["./playground"] });
|
|
195
160
|
```
|
|
196
161
|
|
|
197
|
-
`@nuxt/eslint` supplies the Vue and TypeScript rules
|
|
198
|
-
AntelopeJS layers differ from it — single-word page components, `any` and `{}` as
|
|
199
|
-
load-bearing types in the interface layer, `_`-prefixed unused bindings, and import order
|
|
200
|
-
left to the formatter.
|
|
201
|
-
|
|
202
|
-
Formatting rules are deliberately absent, `vue/max-attributes-per-line` included: oxfmt
|
|
203
|
-
formats `.vue`, and a lint rule that also reflows markup would fight it on every save.
|
|
204
|
-
Declare `@nuxt/eslint-config` explicitly — nine layers use it today through
|
|
205
|
-
`@nuxt/eslint` without declaring it.
|
|
162
|
+
`@nuxt/eslint-config` supplies the Vue and TypeScript rules. The preset only records where AntelopeJS layers differ: single-word page components, `any` and `{}` allowed, `_`-prefixed unused bindings, and import order left alone. It sets no formatting rule, since oxfmt formats `.vue`. Pass `rules` to layer your own on top, and declare `@nuxt/eslint-config` in the front end's `package.json`.
|
|
206
163
|
|
|
207
164
|
## Knip
|
|
208
165
|
|
|
@@ -213,39 +170,25 @@ import { antelopeKnipConfig } from "@antelopejs/tooling-configs/knip";
|
|
|
213
170
|
export default antelopeKnipConfig();
|
|
214
171
|
```
|
|
215
172
|
|
|
216
|
-
The defaults declare what Knip cannot infer for an AntelopeJS module:
|
|
217
|
-
subpaths as public API, and `src/test/**` plus a root `antelope.test.ts` as entry points,
|
|
218
|
-
since `ajs module test` is not a runner Knip has a plugin for. Without them, Knip reports
|
|
219
|
-
the whole test suite as dead code.
|
|
173
|
+
The defaults declare what Knip cannot infer for an AntelopeJS module:
|
|
220
174
|
|
|
221
|
-
`src/
|
|
222
|
-
|
|
223
|
-
repeating it only earns a "redundant pattern" hint.
|
|
175
|
+
- entry points: `src/interfaces/**/*.ts` (public API), `src/test/**` and `antelope.test.ts` (run by `ajs module test`), and `scripts/**`;
|
|
176
|
+
- ignored: `dist/**`, `playground/**`, `.antelope/**`, and the `@antelopejs/*` dependencies, which the runtime loads by name.
|
|
224
177
|
|
|
225
|
-
|
|
226
|
-
`frontend-vue/` analysed can add it under Knip's `workspaces` without the preset
|
|
227
|
-
overriding the choice.
|
|
178
|
+
`entry`, `project`, `ignore`, `ignoreDependencies` and `ignoreBinaries` options are appended to the defaults. `frontend-vue/` stays out of `project`, so a repository can opt it in through Knip's `workspaces`.
|
|
228
179
|
|
|
229
180
|
## Interface ranges
|
|
230
181
|
|
|
231
|
-
`@antelopejs/core` keeps one copy of each `@antelopejs/interface-*` package at startup
|
|
232
|
-
one its implementing module installed, and refuses to start when a loaded module declares a
|
|
233
|
-
range that copy falls outside. An exact pin (`0.1.7`) or a 0.x caret (`^0.1.2` stops at
|
|
234
|
-
`0.2.0`) therefore breaks a module's startup at the next interface release, with no change to
|
|
235
|
-
the module.
|
|
182
|
+
`@antelopejs/core` keeps one copy of each `@antelopejs/interface-*` package, the one its implementing module installed, and refuses to start when a module declares a range that copy falls outside. An exact pin (`0.1.7`) or a 0.x caret (`^0.1.2` stops at `0.2.0`) therefore breaks startup at the next interface release.
|
|
236
183
|
|
|
237
|
-
`antelopejs-check-interface-ranges` fails on such a range in `dependencies` or
|
|
238
|
-
`optionalDependencies`, in every `package.json` git tracks in the repository (playgrounds and
|
|
239
|
-
front-end layers included), whatever directory it runs from:
|
|
184
|
+
`antelopejs-check-interface-ranges` fails on such a range in `dependencies` or `optionalDependencies`, in every `package.json` git tracks in the repository, from any directory:
|
|
240
185
|
|
|
241
186
|
| The package… | must declare |
|
|
242
187
|
| ------------------------------------------------- | -------------------------------------------- |
|
|
243
188
|
| consumes the interface | `>=<floor> <1.0.0` (`<next major>` from 1.0) |
|
|
244
189
|
| implements it (listed in `antelopeJs.implements`) | `>=<floor> <0.<minor + 1>.0` while it is 0.x |
|
|
245
190
|
|
|
246
|
-
An implementer
|
|
247
|
-
does not implement. When the implemented interface sits in the same repository, its version is
|
|
248
|
-
the floor to use. `workspace:`, `file:` and `link:` specs are left alone.
|
|
191
|
+
An implementer must never be handed a breaking minor it does not implement. `workspace:`, `file:` and `link:` specs are skipped. Pass paths to check only those manifests.
|
|
249
192
|
|
|
250
193
|
```jsonc
|
|
251
194
|
// package.json
|
|
@@ -256,12 +199,23 @@ the floor to use. `workspace:`, `file:` and `link:` specs are left alone.
|
|
|
256
199
|
}
|
|
257
200
|
```
|
|
258
201
|
|
|
259
|
-
Pass paths to check only those manifests.
|
|
260
|
-
|
|
261
202
|
## Vendored anti-slop
|
|
262
203
|
|
|
263
|
-
`src/oxc/anti-slop/` is a copy of upstream,
|
|
264
|
-
|
|
265
|
-
|
|
204
|
+
`src/oxc/anti-slop/` is a byte-identical copy of upstream, so it can be diffed against new releases; `src/oxc/anti-slop/VENDORED.md` records the commit and any local edit. This repository does not format or lint it. Upstream is MIT (`src/oxc/anti-slop/LICENSE`).
|
|
205
|
+
|
|
206
|
+
## Documentation guardrail
|
|
207
|
+
|
|
208
|
+
The [documentation action](./docs/documentation-checks.md) checks local Markdown
|
|
209
|
+
links and explicitly labeled compatibility tables. Consumers can also opt in
|
|
210
|
+
complete TypeScript examples and reference-page export coverage. Pin
|
|
211
|
+
`AntelopeJS/tooling-configs/actions/docs` to a full commit SHA; no npm release is
|
|
212
|
+
required. The guide includes CI and local commands, annotation syntax, and the
|
|
213
|
+
checks that remain the author's responsibility.
|
|
214
|
+
|
|
215
|
+
## Contributing
|
|
216
|
+
|
|
217
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md). `pnpm install`, then `pnpm checks` runs the typecheck, lint, format check and tests.
|
|
218
|
+
|
|
219
|
+
## License
|
|
266
220
|
|
|
267
|
-
|
|
221
|
+
[Apache-2.0](./LICENSE), except the vendored anti-slop rules (MIT).
|
package/package.json
CHANGED
|
@@ -1,14 +1,20 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/tooling-configs",
|
|
3
|
-
"version": "0.0.
|
|
4
|
-
"description": "Shared tooling presets for AntelopeJS
|
|
3
|
+
"version": "0.0.9",
|
|
4
|
+
"description": "Shared tooling presets for AntelopeJS repositories: oxlint (with the vendored anti-slop rules), oxfmt, ESLint for Nuxt layers, Knip, and an interface range check",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"antelopejs",
|
|
7
7
|
"anti-slop",
|
|
8
|
+
"eslint",
|
|
8
9
|
"knip",
|
|
9
10
|
"oxc",
|
|
11
|
+
"oxfmt",
|
|
10
12
|
"oxlint"
|
|
11
13
|
],
|
|
14
|
+
"homepage": "https://github.com/AntelopeJS/tooling-configs#readme",
|
|
15
|
+
"bugs": {
|
|
16
|
+
"url": "https://github.com/AntelopeJS/tooling-configs/issues"
|
|
17
|
+
},
|
|
12
18
|
"license": "Apache-2.0",
|
|
13
19
|
"repository": {
|
|
14
20
|
"type": "git",
|