@antelopejs/tooling-configs 0.0.7 → 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 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="NPM version" src="https://img.shields.io/npm/v/@antelopejs/tooling-configs.svg?style=for-the-badge&labelColor=000000"></a>
5
- <a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/tooling-configs.svg?style=for-the-badge&labelColor=000000"></a>
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 tooling presets for AntelopeJS repositories: [oxlint](https://oxc.rs) (including
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
- Together they replace Biome outright — lint, format and import order — and Prettier in the
15
- Nuxt layers, since oxfmt formats `.vue` and sorts Tailwind classes natively. The front end
16
- keeps ESLint for linting, from a shared config here.
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
- ## Requirements
16
+ ## What's in the box
19
17
 
20
- Node **24** (or at least 22.18). oxlint reads `oxlint.config.ts` and loads JS plugins by
21
- executing TypeScript, which earlier runtimes cannot do.
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 @antelopejs/tooling-configs
32
+ pnpm add -D @antelopejs/tooling-configs oxlint@1.81.0 oxfmt
27
33
  ```
28
34
 
29
- Add `eslint-plugin-perfectionist` too unless you turn import sorting off — it is an
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
- ```bash
33
- pnpm add -D eslint-plugin-perfectionist
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 depends on for `@oxlint/plugins`
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
- // Only read from the root config, never from a preset.
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
- Type-aware rules (`typescript/no-floating-promises`) also need the tsgolint binary:
71
+ ### What the preset turns on
65
72
 
66
- ```bash
67
- pnpm add -D oxlint-tsgolint
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
- ### What the preset turns on
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
- | Group | Contents |
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: false, // leave imports alone
90
- typeAware: false, // no tsgolint in this repository
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
- `correctness` is raised to error deliberately. oxlint reports it as warnings, and warnings
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
- `antiSlop` and `complexity` default to warnings on purpose: a repository adopting them
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,51 +132,23 @@ export default antelopeFmtPreset();
135
132
  }
136
133
  ```
137
134
 
138
- ### The house style
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.
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.
154
136
 
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.
158
-
159
- Extra ignores are **added** to the shared ones rather than replacing them, so a repository
160
- adopting oxfmt in stages can park a directory without losing the rest:
161
-
162
- ```ts
163
- export default antelopeFmtPreset({ ignorePatterns: ["frontend-vue/**"] });
164
- ```
165
-
166
- 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:
167
138
 
168
139
  ```ts
140
+ // oxfmt.config.ts
169
141
  export default antelopeFmtPreset({
170
- tailwindStylesheet: "./assets/css/main.css",
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
171
144
  });
172
145
  ```
173
146
 
174
- ### Replacing Biome
147
+ ### Replace Biome
175
148
 
176
- Per repository: delete `biome.json` and the `@biomejs/biome` dependency, point `lint`,
177
- `lint:fix` and `format` at oxlint and oxfmt, and port anything the Biome config carried
178
- that the preset does not (`noRestrictedImports` guards become `import/no-cycle`). Reformat
179
- in its own commit and record it in `.git-blame-ignore-revs`, which GitHub honours, so the
180
- 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.
181
150
 
182
- ## ESLint (front ends)
151
+ ## ESLint (Nuxt front ends)
183
152
 
184
153
  oxlint does not lint `.vue` files yet, so the front end stays on ESLint:
185
154
 
@@ -190,15 +159,7 @@ import { antelopeNuxtConfig } from "@antelopejs/tooling-configs/eslint";
190
159
  export default antelopeNuxtConfig({ dirs: ["./playground"] });
191
160
  ```
192
161
 
193
- `@nuxt/eslint` supplies the Vue and TypeScript rules; the preset only records where
194
- AntelopeJS layers differ from it — single-word page components, `any` and `{}` as
195
- load-bearing types in the interface layer, `_`-prefixed unused bindings, and import order
196
- left to the formatter.
197
-
198
- Formatting rules are deliberately absent, `vue/max-attributes-per-line` included: oxfmt
199
- formats `.vue`, and a lint rule that also reflows markup would fight it on every save.
200
- Declare `@nuxt/eslint-config` explicitly — nine layers use it today through
201
- `@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`.
202
163
 
203
164
  ## Knip
204
165
 
@@ -209,39 +170,25 @@ import { antelopeKnipConfig } from "@antelopejs/tooling-configs/knip";
209
170
  export default antelopeKnipConfig();
210
171
  ```
211
172
 
212
- The defaults declare what Knip cannot infer for an AntelopeJS module: the interface
213
- subpaths as public API, and `src/test/**` plus a root `antelope.test.ts` as entry points,
214
- since `ajs module test` is not a runner Knip has a plugin for. Without them, Knip reports
215
- the whole test suite as dead code.
173
+ The defaults declare what Knip cannot infer for an AntelopeJS module:
216
174
 
217
- `src/index.ts` is not among them on purpose: Knip already maps the `main`/`bin` of
218
- package.json (`dist/index.js`) back onto `src/index.ts`, ahead of the `dist/**` ignore, so
219
- 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.
220
177
 
221
- The front end is left out of `project` rather than ignored, so a repository that wants
222
- `frontend-vue/` analysed can add it under Knip's `workspaces` without the preset
223
- 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`.
224
179
 
225
180
  ## Interface ranges
226
181
 
227
- `@antelopejs/core` keeps one copy of each `@antelopejs/interface-*` package at startup, the
228
- one its implementing module installed, and refuses to start when a loaded module declares a
229
- range that copy falls outside. An exact pin (`0.1.7`) or a 0.x caret (`^0.1.2` stops at
230
- `0.2.0`) therefore breaks a module's startup at the next interface release, with no change to
231
- 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.
232
183
 
233
- `antelopejs-check-interface-ranges` fails on such a range in `dependencies` or
234
- `optionalDependencies`, in every `package.json` git tracks in the repository (playgrounds and
235
- 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:
236
185
 
237
186
  | The package… | must declare |
238
187
  | ------------------------------------------------- | -------------------------------------------- |
239
188
  | consumes the interface | `>=<floor> <1.0.0` (`<next major>` from 1.0) |
240
189
  | implements it (listed in `antelopeJs.implements`) | `>=<floor> <0.<minor + 1>.0` while it is 0.x |
241
190
 
242
- An implementer is the opposite case on purpose: it must never be handed a breaking minor it
243
- does not implement. When the implemented interface sits in the same repository, its version is
244
- 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.
245
192
 
246
193
  ```jsonc
247
194
  // package.json
@@ -252,12 +199,23 @@ the floor to use. `workspace:`, `file:` and `link:` specs are left alone.
252
199
  }
253
200
  ```
254
201
 
255
- Pass paths to check only those manifests.
256
-
257
202
  ## Vendored anti-slop
258
203
 
259
- `src/oxc/anti-slop/` is a copy of upstream, kept byte-identical so it can be diffed
260
- against new releases. See `src/oxc/anti-slop/VENDORED.md` for the commit it came from and
261
- any local edits. It is excluded from this repository's own formatting and linting.
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
262
220
 
263
- Upstream is MIT (`src/oxc/anti-slop/LICENSE`); the rest of this repository is Apache-2.0.
221
+ [Apache-2.0](./LICENSE), except the vendored anti-slop rules (MIT).
package/dist/oxc/fmt.mjs CHANGED
@@ -17,6 +17,12 @@ const ANTELOPE_STYLE = {
17
17
  trailingComma: "all"
18
18
  };
19
19
  /**
20
+ * Files that release tooling writes and commits without formatting them.
21
+ * changelogen puts two spaces after the ⚠️ of a breaking change, so the first
22
+ * release with one leaves the default branch failing `oxfmt --check`.
23
+ */
24
+ const GENERATED_IGNORE_PATTERNS = ["**/CHANGELOG.md"];
25
+ /**
20
26
  * The shared AntelopeJS oxfmt preset.
21
27
  *
22
28
  * Import order is deliberately absent: `perfectionist/sort-imports` owns it on
@@ -44,6 +50,7 @@ function antelopeFmtPreset(options = {}) {
44
50
  ignorePatterns: [
45
51
  ...IGNORE_PATTERNS,
46
52
  ...AGENT_IGNORE_PATTERNS,
53
+ ...GENERATED_IGNORE_PATTERNS,
47
54
  ...ignorePatterns
48
55
  ]
49
56
  });
package/package.json CHANGED
@@ -1,14 +1,20 @@
1
1
  {
2
2
  "name": "@antelopejs/tooling-configs",
3
- "version": "0.0.7",
4
- "description": "Shared tooling presets for AntelopeJS projects: oxlint (incl. vendored anti-slop) and Knip",
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",