@codefast/cli 0.14.0 → 0.15.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/CHANGELOG.md +51 -0
- package/README.md +70 -5
- package/dist/arrange/simplify/variant-classname-probe.js +2 -11
- package/dist/audit/command.js +40 -0
- package/dist/audit/comments/domain/comment-dividers.js +8 -1
- package/dist/audit/display-names/domain/display-names.js +4 -3
- package/dist/audit/domain/types.d.ts +94 -0
- package/dist/audit/engines/cli-result.d.ts +13 -0
- package/dist/audit/engines/cli-result.js +22 -0
- package/dist/audit/engines/cli-schema.d.ts +18 -0
- package/dist/audit/engines/cli-schema.js +12 -0
- package/dist/audit/engines/domain/node-floor.d.ts +34 -0
- package/dist/audit/engines/domain/node-floor.js +40 -0
- package/dist/audit/engines/domain/range-gaps.d.ts +21 -0
- package/dist/audit/engines/domain/range-gaps.js +136 -0
- package/dist/audit/engines/output.d.ts +7 -0
- package/dist/audit/engines/output.js +40 -0
- package/dist/audit/engines/prepare.d.ts +16 -0
- package/dist/audit/engines/prepare.js +12 -0
- package/dist/audit/engines/run.d.ts +18 -0
- package/dist/audit/engines/run.js +225 -0
- package/dist/audit/props/cli-result.d.ts +13 -0
- package/dist/audit/props/cli-result.js +22 -0
- package/dist/audit/props/cli-schema.d.ts +18 -0
- package/dist/audit/props/cli-schema.js +12 -0
- package/dist/audit/props/domain/props-intersection.d.ts +56 -0
- package/dist/audit/props/domain/props-intersection.js +189 -0
- package/dist/audit/props/output.d.ts +7 -0
- package/dist/audit/props/output.js +21 -0
- package/dist/audit/props/prepare.d.ts +13 -0
- package/dist/audit/props/prepare.js +9 -0
- package/dist/audit/props/run.d.ts +17 -0
- package/dist/audit/props/run.js +57 -0
- package/dist/audit/props/type-probe.d.ts +23 -0
- package/dist/audit/props/type-probe.js +85 -0
- package/dist/core/config/schema.d.ts +1 -0
- package/dist/core/config/schema.js +1 -0
- package/dist/core/type-server.d.ts +21 -0
- package/dist/core/type-server.js +32 -0
- package/package.json +6 -5
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,56 @@
|
|
|
1
1
|
# @codefast/cli
|
|
2
2
|
|
|
3
|
+
## 0.15.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [#1104](https://github.com/codefastlabs/codefast/pull/1104) `codefast audit engines` now holds the workspace root's `engines.node` floor, when written `>=X.Y.Z`, to the
|
|
8
|
+
`engines.node` of every dependency any workspace package installs, runtime and dev alike, from the root floor up
|
|
9
|
+
(short-lived odd lines below `.node-version` aside). A gap is reported as `root-outside-dependency-engines`, once per
|
|
10
|
+
dependency range, naming the packages that install it. The root is still never listed among `floors` and is checked only
|
|
11
|
+
when the target reaches it.
|
|
12
|
+
|
|
13
|
+
- [#1068](https://github.com/codefastlabs/codefast/pull/1068) Add `codefast audit engines`, which holds each workspace package's own Node floor (`engines.node`) to what runs on it: a
|
|
14
|
+
published package declares one as `>=X.Y.Z`, every runtime dependency's `engines.node` admits each release from the
|
|
15
|
+
floor up (odd lines below the newest tested one aside), every dev dependency's admits the floor and the newest release
|
|
16
|
+
CI tests on (`.node-version`), and the `@types/node` the lockfile resolves declares nothing the floor lacks. A violation
|
|
17
|
+
names the dependency, its range and the releases it leaves out. `--json` lists every floor, enough to plan one CI leg
|
|
18
|
+
per floor.
|
|
19
|
+
|
|
20
|
+
- [#1072](https://github.com/codefastlabs/codefast/pull/1072) `codefast audit props` also reads a component's props parameter annotated inline with `&`: in a `.tsx` file, the first
|
|
21
|
+
parameter of a module-level component whose annotation is an intersection at its top level, such as
|
|
22
|
+
`function ListItem({ href, ...props }: ComponentProps<"li"> & { href: string })`. The type server judges it like an
|
|
23
|
+
alias — a union, a type parameter or a non-object part keeps it — and a reported one asks to be named as an interface.
|
|
24
|
+
`audit.props.allowlist` takes the annotation's first line as written.
|
|
25
|
+
|
|
26
|
+
- [#1071](https://github.com/codefastlabs/codefast/pull/1071) Add `codefast audit props`, which reports every `*Props` type alias joined with `&` that an interface could express — at
|
|
27
|
+
the alias's top level, or passed to the type it wraps. The native TypeScript type server decides it: an alias keeps its
|
|
28
|
+
`&` when a part resolves to a union, a type parameter or a mapped type over one, or no object at all, so the forms that
|
|
29
|
+
must stay intersections need no allowlist. A part that does not resolve is reported rather than passed. The type server
|
|
30
|
+
starts only for a file that holds a candidate and needs `typescript` (v7); `audit.props.allowlist` takes the alias's
|
|
31
|
+
first line as written, or `path:<line>`.
|
|
32
|
+
|
|
33
|
+
- [#1101](https://github.com/codefastlabs/codefast/pull/1101) `codefast audit display-names` also checks the names given to `Module.fromBindings(…)` and
|
|
34
|
+
`createAutoRegisterRegistry(…)` — both are modules, so their names follow the module rule, `<namespace>:<PascalName>`.
|
|
35
|
+
|
|
36
|
+
- [#1068](https://github.com/codefastlabs/codefast/pull/1068) Lower the Node.js floor from 24 to the lowest release the package, its dependencies and its full test suite run on:
|
|
37
|
+
22.12 for `@codefast/cli` and `@codefast/tailwind-variants`, 22.18 for `@codefast/di` and `@codefast/di-testing`, and
|
|
38
|
+
22.22.2 for `@codefast/theme`, `@codefast/tracking` and `@codefast/ui`. Each floor is type-checked against what Node 22
|
|
39
|
+
ships and proven by running the package's tests on that release in CI.
|
|
40
|
+
|
|
41
|
+
### Patch Changes
|
|
42
|
+
|
|
43
|
+
- [#1086](https://github.com/codefastlabs/codefast/pull/1086) `codefast audit comments` reads a titled rule that opens a block comment without closing it, such as
|
|
44
|
+
`/* ── Status colours ──` followed by prose and `*/`, as the heading of a doc block rather than a divider, so `--fix` no
|
|
45
|
+
longer closes the comment on that line and leaves the prose below it outside the comment.
|
|
46
|
+
|
|
47
|
+
- [#1085](https://github.com/codefastlabs/codefast/pull/1085) `codefast audit props` reads an inline `&` parameter only on a component — a module-level function with a capitalised
|
|
48
|
+
name, declared as a function or held by a `const`, directly or through a call such as `memo(…)` — so a closure inside a
|
|
49
|
+
component, like `const targetFor = (event: Pick<…> & Partial<…>) => …`, and a lowercase helper are no longer reported.
|
|
50
|
+
|
|
51
|
+
- [#1120](https://github.com/codefastlabs/codefast/pull/1120) `audit display-names` reads a module name from `Module.create`, `Module.createAsync` and `Module.fromBindings` only,
|
|
52
|
+
since `@codefast/di` no longer has the `SyncModule` and `AsyncModule` factory companions.
|
|
53
|
+
|
|
3
54
|
## 0.14.0
|
|
4
55
|
|
|
5
56
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -22,7 +22,7 @@ encode an opinionated house style (called out below) that you can adopt, ignore,
|
|
|
22
22
|
|
|
23
23
|
## Requirements
|
|
24
24
|
|
|
25
|
-
- **Node.js ≥
|
|
25
|
+
- **Node.js ≥ 22.12** (the CLI is published as ESM).
|
|
26
26
|
- **TypeScript ≥ 7** to type-check a config written with `defineConfig`, and for
|
|
27
27
|
`arrange simplify --fold-variant-classname`, the one command that loads `typescript` (an optional peer).
|
|
28
28
|
- **A project root — workspace or single package.** Commands resolve their root by walking up from the current
|
|
@@ -112,7 +112,9 @@ codefast # Codefast monorepo developer CLI
|
|
|
112
112
|
│ ├─ imports [target] # banned import forms (React by-name, Zod namespace in front-end, …)
|
|
113
113
|
│ ├─ assertions [target] # double type assertions through unknown/any (x as unknown as T)
|
|
114
114
|
│ ├─ display-names [target] # token()/tag()/module names breaking the <namespace>:<Name> convention
|
|
115
|
+
│ ├─ props [target] # *Props aliases joined with & that an interface could express (TS type server)
|
|
115
116
|
│ ├─ publish [target] # what breaks a consumer's install: #/ imports, unshipped targets, @source paths
|
|
117
|
+
│ ├─ engines [target] # Node floors (engines.node) outside a dependency's engines or their @types/node line
|
|
116
118
|
│ ├─ layers [target] # value imports pointing up a package's configured layers
|
|
117
119
|
│ └─ comments [target] # section dividers not in the one allowed form
|
|
118
120
|
│ └─ --fix # rewrite every fixable divider in place (the only audit that writes)
|
|
@@ -146,15 +148,18 @@ Every command also responds to `--help`; each command's section below explains w
|
|
|
146
148
|
| `audit imports` | Enforce the import policy (React by-name, Zod namespace in front-end) | no (report only) |
|
|
147
149
|
| `audit assertions` | Report double type assertions through `unknown` / `any`, tests included | no |
|
|
148
150
|
| `audit display-names` | Enforce the `namespace:Name` display-name convention | no |
|
|
151
|
+
| `audit props` | Report props types joined with `&` that an interface could express | no |
|
|
149
152
|
| `audit publish` | Report what would break a consumer's install of a published package | no |
|
|
153
|
+
| `audit engines` | Report each package's Node floor that does not hold | no |
|
|
150
154
|
| `audit layers` | Report value imports that point up a package's configured layers | no |
|
|
151
155
|
| `audit comments` | Check doc-comment conventions; repair section dividers | `--fix` only |
|
|
152
156
|
|
|
153
157
|
**Which of these are for you?** `arrange`, `mirror`, `pack-slim`, `tag`, `audit links`, `audit assertions`,
|
|
154
|
-
`audit layers`, and `audit
|
|
155
|
-
with `tsc`. The other
|
|
156
|
-
specific comment/divider grammar, a `namespace:Name` scheme for `@codefast/di` tokens
|
|
157
|
-
project; otherwise skip them, or use an allowlist to narrow their
|
|
158
|
+
`audit layers`, `audit publish`, and `audit engines` are general-purpose — they work for any pnpm workspace or single
|
|
159
|
+
package that builds with `tsc`. The other five audits encode codefast's own house style (logical Tailwind directions,
|
|
160
|
+
named React imports, a specific comment/divider grammar, a `namespace:Name` scheme for `@codefast/di` tokens, interfaces
|
|
161
|
+
for component props). Adopt them if they fit your project; otherwise skip them, or use an allowlist to narrow their
|
|
162
|
+
scope.
|
|
158
163
|
|
|
159
164
|
## `arrange`
|
|
160
165
|
|
|
@@ -373,6 +378,35 @@ codefast audit assertions --json # machine-readable summary
|
|
|
373
378
|
Configure exceptions via `audit.assertions.allowlist` — each entry is the assertion as written or
|
|
374
379
|
`repo/relative/path.ts:<assertion>` — though the inline directive keeps the reason beside the code it excuses.
|
|
375
380
|
|
|
381
|
+
### `audit props`
|
|
382
|
+
|
|
383
|
+
Reports every `*Props` type alias joined with `&` that an interface could express instead — at the alias's top level
|
|
384
|
+
(`type ButtonProps = ComponentProps<"button"> & ButtonVariants & { … }`) or passed to the type it wraps
|
|
385
|
+
(`type ScrollAreaProps = ScopedProps<RootProps & ContextValue>`) — and every component parameter annotated inline with
|
|
386
|
+
one: in a `.tsx` file, the first parameter of a component whose annotation is an intersection at its top level
|
|
387
|
+
(`function ListItem({ href, ...props }: ComponentProps<"li"> & { href: string })`), which wants naming as an interface.
|
|
388
|
+
A component is a module-level function with a capitalised name, as JSX renders one — a function declaration, or a
|
|
389
|
+
`const` holding an arrow or function expression, directly or through a call such as `memo(…)`. A function nested in
|
|
390
|
+
another (an event handler, a callback) takes no props, so its parameters are never read. An interface checks its members
|
|
391
|
+
against every base where it is declared, so a conflicting prop fails there (TS2430, or TS2320 between two bases); `&`
|
|
392
|
+
intersects the two silently and the narrowed prop only fails at a call site.
|
|
393
|
+
|
|
394
|
+
Whether a part can be extended is the type checker's call, not a name list: the audit asks the native TypeScript type
|
|
395
|
+
server (`typescript/unstable/sync`) what each part resolves to, and keeps the `&` when one is a union (only `&`
|
|
396
|
+
distributes over its members), a type parameter or a mapped type over one (an interface cannot extend either), or no
|
|
397
|
+
object at all. A part that does not resolve is reported, since nothing can be said about it — on a workspace whose
|
|
398
|
+
packages consume each other's `dist/`, build first. The type server starts only once a file holds a candidate, and needs
|
|
399
|
+
the `typescript` package (v7) resolvable from the target and a `tsconfig.json` that includes each file.
|
|
400
|
+
|
|
401
|
+
```bash
|
|
402
|
+
codefast audit props # whole repo
|
|
403
|
+
codefast audit props packages/ui/src # explicit target
|
|
404
|
+
codefast audit props --json # machine-readable summary
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
Configure exceptions via `audit.props.allowlist` — each entry is the alias's, or the parameter annotation's, first line
|
|
408
|
+
as written or `repo/relative/path.tsx:<line>` — though a type that must stay an intersection needs none.
|
|
409
|
+
|
|
376
410
|
### `audit publish`
|
|
377
411
|
|
|
378
412
|
Reports what would break a consumer's install of a published package, while it can still be fixed:
|
|
@@ -392,6 +426,36 @@ codefast audit publish # every published package in the work
|
|
|
392
426
|
codefast audit publish --json # machine-readable summary
|
|
393
427
|
```
|
|
394
428
|
|
|
429
|
+
### `audit engines`
|
|
430
|
+
|
|
431
|
+
_General-purpose._ Holds each workspace package's own Node floor — its `engines.node` — to what actually runs on it, so
|
|
432
|
+
packages can sit on different floors, each as low as the package can go. It reports:
|
|
433
|
+
|
|
434
|
+
- a published package that declares no floor, and a floor not written `>=X.Y.Z`;
|
|
435
|
+
- a release the floor claims that a dependency's `engines.node` leaves out, named with the dependency, its range and the
|
|
436
|
+
sub-range it misses. A runtime dependency (`dependencies`, `peerDependencies`, `optionalDependencies`) a consumer
|
|
437
|
+
installs must admit every release from the floor up — the odd majors below the one `.node-version` pins aside, since
|
|
438
|
+
they reach end-of-life without becoming LTS — so `^22.18.0 || >=24.11.0` fails a `>=22.18.0` floor on 24.0–24.10. A
|
|
439
|
+
dev dependency only runs the package's tests, so it must admit the floor and the `.node-version` release CI runs them
|
|
440
|
+
on. A workspace dependency is read from its manifest, any other from the package's own `node_modules`, so run the
|
|
441
|
+
audit after the install;
|
|
442
|
+
- an `@types/node` the lockfile (`pnpm-lock.yaml`) resolves on another major than the floor or on a newer minor, where
|
|
443
|
+
the compiler would accept APIs the floor lacks.
|
|
444
|
+
|
|
445
|
+
The workspace root's own `engines.node`, when written `>=X.Y.Z`, is the contributors' floor rather than one any package
|
|
446
|
+
inherits: a contributor on it builds and tests every package, so every dependency any of them installs, runtime and dev
|
|
447
|
+
alike, must admit every release from the root floor up, short-lived odd lines aside. Each gap is reported once per
|
|
448
|
+
dependency range, naming the packages that install it. The root is never listed among the floors and is checked only
|
|
449
|
+
when the target reaches it. A narrower `[target]` checks only the packages it reaches, still against every floor they
|
|
450
|
+
depend on. `--json` lists every floor with its package directory, which is enough to plan one CI leg per floor. It takes
|
|
451
|
+
no allowlist.
|
|
452
|
+
|
|
453
|
+
```bash
|
|
454
|
+
codefast audit engines # every package in the workspace
|
|
455
|
+
codefast audit engines packages/di # one package
|
|
456
|
+
codefast audit engines --json # machine-readable summary, floors included
|
|
457
|
+
```
|
|
458
|
+
|
|
395
459
|
### `audit layers`
|
|
396
460
|
|
|
397
461
|
_General-purpose._ Holds a package's `src/` to the layering its architecture states. You list the layers in
|
|
@@ -656,6 +720,7 @@ pnpm run cli:audit:assertions # codefast audit assertions
|
|
|
656
720
|
pnpm run cli:audit:display-names # codefast audit display-names
|
|
657
721
|
pnpm run cli:audit:layers # codefast audit layers
|
|
658
722
|
pnpm run cli:audit:publish # codefast audit publish
|
|
723
|
+
pnpm run cli:audit:engines # codefast audit engines
|
|
659
724
|
```
|
|
660
725
|
|
|
661
726
|
`pnpm run version-packages` runs `changeset version` and then `codefast tag`, so published APIs are stamped at release,
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/** Type probe that asks whether a variant function's options accept a folded `className`. */
|
|
2
|
-
import {
|
|
2
|
+
import { loadTypeServer } from "#core/type-server";
|
|
3
3
|
// ── Type inspection ──────────────────────────────────────────────────────────────────────────────────────────────────
|
|
4
4
|
/** The type of the callee's first-parameter `className` (preferred) or `class` option, if any. */
|
|
5
5
|
function classNameOptionType(checker, optionsType) {
|
|
@@ -51,15 +51,6 @@ function classNameAcceptanceAt(checker, callKind, filePath, offset) {
|
|
|
51
51
|
};
|
|
52
52
|
}
|
|
53
53
|
// ── Probe lifecycle ──────────────────────────────────────────────────────────────────────────────────────────────────
|
|
54
|
-
/** Loads the native TypeScript type-server API, or fails with a coded error naming the missing package. */
|
|
55
|
-
async function loadTypeServer() {
|
|
56
|
-
try {
|
|
57
|
-
return await import("typescript/unstable/sync");
|
|
58
|
-
}
|
|
59
|
-
catch (cause) {
|
|
60
|
-
throw new AppError("INFRA_FAILURE", `--fold-variant-classname needs the "typescript" package (v7) resolvable from the target: ${messageFrom(cause)}`, cause);
|
|
61
|
-
}
|
|
62
|
-
}
|
|
63
54
|
/**
|
|
64
55
|
* Creates a type probe over the native TypeScript type server for the opt-in `className` fold.
|
|
65
56
|
*
|
|
@@ -68,7 +59,7 @@ async function loadTypeServer() {
|
|
|
68
59
|
* @since 0.11.0
|
|
69
60
|
*/
|
|
70
61
|
export async function createVariantClassNameProbe() {
|
|
71
|
-
const sync = await loadTypeServer();
|
|
62
|
+
const sync = await loadTypeServer("--fold-variant-classname");
|
|
72
63
|
const api = new sync.API();
|
|
73
64
|
const callKind = sync.SignatureKind.Call;
|
|
74
65
|
return {
|
package/dist/audit/command.js
CHANGED
|
@@ -14,6 +14,11 @@ import { displayNameAuditRunRequestSchema } from "#audit/display-names/cli-schem
|
|
|
14
14
|
import { presentDisplayNameAuditResult } from "#audit/display-names/output";
|
|
15
15
|
import { prepareDisplayNameAudit } from "#audit/display-names/prepare";
|
|
16
16
|
import { runDisplayNameAudit } from "#audit/display-names/run";
|
|
17
|
+
import { exitCodeForEnginesAuditResult, formatEnginesAuditJsonOutput } from "#audit/engines/cli-result";
|
|
18
|
+
import { enginesAuditRunRequestSchema } from "#audit/engines/cli-schema";
|
|
19
|
+
import { presentEnginesAuditResult } from "#audit/engines/output";
|
|
20
|
+
import { prepareEnginesAudit } from "#audit/engines/prepare";
|
|
21
|
+
import { runEnginesAudit } from "#audit/engines/run";
|
|
17
22
|
import { exitCodeForImportsAuditResult, formatImportsAuditJsonOutput } from "#audit/imports/cli-result";
|
|
18
23
|
import { importsAuditRunRequestSchema } from "#audit/imports/cli-schema";
|
|
19
24
|
import { presentImportsAuditResult } from "#audit/imports/output";
|
|
@@ -29,6 +34,11 @@ import { linkAuditRunRequestSchema } from "#audit/links/cli-schema";
|
|
|
29
34
|
import { presentLinkAuditResult } from "#audit/links/output";
|
|
30
35
|
import { prepareLinkAudit } from "#audit/links/prepare";
|
|
31
36
|
import { runLinkAudit } from "#audit/links/run";
|
|
37
|
+
import { exitCodeForPropsAuditResult, formatPropsAuditJsonOutput } from "#audit/props/cli-result";
|
|
38
|
+
import { propsAuditRunRequestSchema } from "#audit/props/cli-schema";
|
|
39
|
+
import { presentPropsAuditResult } from "#audit/props/output";
|
|
40
|
+
import { preparePropsAudit } from "#audit/props/prepare";
|
|
41
|
+
import { runPropsAudit } from "#audit/props/run";
|
|
32
42
|
import { exitCodeForPublishAuditResult, formatPublishAuditJsonOutput } from "#audit/publish/cli-result";
|
|
33
43
|
import { publishAuditRunRequestSchema } from "#audit/publish/cli-schema";
|
|
34
44
|
import { presentPublishAuditResult } from "#audit/publish/output";
|
|
@@ -121,6 +131,22 @@ const displayNamesCheck = {
|
|
|
121
131
|
formatJson: formatDisplayNameAuditJsonOutput,
|
|
122
132
|
exitCode: exitCodeForDisplayNameAuditResult,
|
|
123
133
|
};
|
|
134
|
+
const propsCheck = {
|
|
135
|
+
name: "props",
|
|
136
|
+
description: "Report component props aliases joined with & that an interface could express, judged by the type checker",
|
|
137
|
+
targetHelp: "Directory or file to scan (default: the repo root)",
|
|
138
|
+
schema: propsAuditRunRequestSchema,
|
|
139
|
+
prepare: preparePropsAudit,
|
|
140
|
+
buildRequest: baseAuditRequest,
|
|
141
|
+
run: (fs, request) => runPropsAudit(fs, {
|
|
142
|
+
rootDir: request.rootDir,
|
|
143
|
+
targetPath: request.targetPath,
|
|
144
|
+
allowlist: request.allowlist ?? [],
|
|
145
|
+
}),
|
|
146
|
+
present: presentPropsAuditResult,
|
|
147
|
+
formatJson: formatPropsAuditJsonOutput,
|
|
148
|
+
exitCode: exitCodeForPropsAuditResult,
|
|
149
|
+
};
|
|
124
150
|
const commentsCheck = {
|
|
125
151
|
name: "comments",
|
|
126
152
|
description: "Report section dividers that are not in the repo's one allowed form",
|
|
@@ -170,6 +196,18 @@ const publishCheck = {
|
|
|
170
196
|
formatJson: formatPublishAuditJsonOutput,
|
|
171
197
|
exitCode: exitCodeForPublishAuditResult,
|
|
172
198
|
};
|
|
199
|
+
const enginesCheck = {
|
|
200
|
+
name: "engines",
|
|
201
|
+
description: "Report Node floors (engines.node) that are missing, malformed, outside a dependency's engines, or off their @types/node line",
|
|
202
|
+
targetHelp: "Directory or file to scan (default: the repo root)",
|
|
203
|
+
schema: enginesAuditRunRequestSchema,
|
|
204
|
+
prepare: prepareEnginesAudit,
|
|
205
|
+
buildRequest: baseAuditRequest,
|
|
206
|
+
run: (fs, request) => runEnginesAudit(fs, { rootDir: request.rootDir, targetPath: request.targetPath }),
|
|
207
|
+
present: presentEnginesAuditResult,
|
|
208
|
+
formatJson: formatEnginesAuditJsonOutput,
|
|
209
|
+
exitCode: exitCodeForEnginesAuditResult,
|
|
210
|
+
};
|
|
173
211
|
/**
|
|
174
212
|
* Adapts an `AuditCheck` descriptor onto the shared command pipeline.
|
|
175
213
|
*/
|
|
@@ -201,8 +239,10 @@ export function createAuditCommand() {
|
|
|
201
239
|
registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(importsCheck));
|
|
202
240
|
registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(assertionsCheck));
|
|
203
241
|
registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(displayNamesCheck));
|
|
242
|
+
registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(propsCheck));
|
|
204
243
|
registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(commentsCheck));
|
|
205
244
|
registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(layersCheck));
|
|
206
245
|
registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(publishCheck));
|
|
246
|
+
registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(enginesCheck));
|
|
207
247
|
return cmd;
|
|
208
248
|
}
|
|
@@ -104,6 +104,10 @@ function readRegionAt(lines, index, language) {
|
|
|
104
104
|
const titled = patterns.titled.exec(line);
|
|
105
105
|
const title = titled?.groups?.title?.trim();
|
|
106
106
|
if (titled !== null && title !== undefined && title.length > 0 && !rulesOnlyPattern.test(title)) {
|
|
107
|
+
// A titled rule that leaves its `/*` open heads the prose below it; closing it would spill that prose into code.
|
|
108
|
+
if (opensUnterminatedBlock(line)) {
|
|
109
|
+
return null;
|
|
110
|
+
}
|
|
107
111
|
const indent = titled.groups?.indent ?? "";
|
|
108
112
|
const canonical = renderDivider(indent, title, language);
|
|
109
113
|
return {
|
|
@@ -125,7 +129,7 @@ function readBannerAt(lines, index, indent, language) {
|
|
|
125
129
|
const line = lines[index];
|
|
126
130
|
const patterns = patternsFor(language);
|
|
127
131
|
// An unterminated `/*` opens a block whose body needs no per-line marker, so the run ends at `*/`.
|
|
128
|
-
const insideBlock =
|
|
132
|
+
const insideBlock = opensUnterminatedBlock(line);
|
|
129
133
|
const body = [];
|
|
130
134
|
let cursor = index + 1;
|
|
131
135
|
while (cursor < lines.length &&
|
|
@@ -152,6 +156,9 @@ function readBannerAt(lines, index, indent, language) {
|
|
|
152
156
|
defect: "legacy-form",
|
|
153
157
|
};
|
|
154
158
|
}
|
|
159
|
+
function opensUnterminatedBlock(line) {
|
|
160
|
+
return line.trimStart().startsWith("/*") && !line.includes("*/");
|
|
161
|
+
}
|
|
155
162
|
function looksLikeTitle(text) {
|
|
156
163
|
return text.length <= MAX_TITLE_LENGTH && !text.endsWith(".");
|
|
157
164
|
}
|
|
@@ -6,14 +6,15 @@ const PASCAL_CASE = /^[A-Z][A-Za-z0-9]*$/;
|
|
|
6
6
|
/** A tag key stands for an attribute a request selects on, so it reads like a property. */
|
|
7
7
|
const CAMEL_CASE = /^[a-z][A-Za-z0-9]*$/;
|
|
8
8
|
/**
|
|
9
|
-
* A bare `token(…)` / `tag(…)` call, or a module factory call
|
|
9
|
+
* A bare `token(…)` / `tag(…)` call, or a module factory call — an auto-register registry is a module too —
|
|
10
|
+
* whose first argument is a string literal.
|
|
10
11
|
*
|
|
11
12
|
* @remarks Generic arguments are skipped up to four levels of nesting, which is deeper than any
|
|
12
13
|
* declaration in the repo. Template literals are not matched: an interpolated name has no fixed
|
|
13
14
|
* text to check. The closing parenthesis is kept when the name is the only argument, so the
|
|
14
15
|
* reported text reads as the call was written.
|
|
15
16
|
*/
|
|
16
|
-
const DISPLAY_NAME_CALL = /(?<![\w$.])(?:(token|tag)\s*(?:<(?:[^<>]|<(?:[^<>]|<(?:[^<>]|<[^<>]*>)*>)*>)*>)?|(
|
|
17
|
+
const DISPLAY_NAME_CALL = /(?<![\w$.])(?:(token|tag)\s*(?:<(?:[^<>]|<(?:[^<>]|<(?:[^<>]|<[^<>]*>)*>)*>)*>)?|(Module)\s*\.\s*(?:create(?:Async)?|fromBindings)|(createAutoRegisterRegistry))\s*\(\s*(["'])((?:(?!\4)[^\\\n]|\\.)*)\4(\s*\))?/g;
|
|
17
18
|
const KIND_LABEL = {
|
|
18
19
|
token: "token display name",
|
|
19
20
|
tag: "tag key",
|
|
@@ -31,7 +32,7 @@ export function auditDisplayNames(sourceText) {
|
|
|
31
32
|
const violations = [];
|
|
32
33
|
for (const match of sourceText.matchAll(DISPLAY_NAME_CALL)) {
|
|
33
34
|
const kind = match[1] === undefined ? "module" : match[1];
|
|
34
|
-
const reason = reasonFor(kind, match[
|
|
35
|
+
const reason = reasonFor(kind, match[5]);
|
|
35
36
|
if (reason === null) {
|
|
36
37
|
continue;
|
|
37
38
|
}
|
|
@@ -104,6 +104,37 @@ export type AssertionAuditResult = {
|
|
|
104
104
|
readonly allowlistedCount: number;
|
|
105
105
|
readonly scannedFileCount: number;
|
|
106
106
|
};
|
|
107
|
+
/**
|
|
108
|
+
* A component props type joined with `&` where an interface could extend every part, or whose parts do not resolve.
|
|
109
|
+
*
|
|
110
|
+
* @since 0.15.0
|
|
111
|
+
*/
|
|
112
|
+
export type PropsViolation = {
|
|
113
|
+
readonly line: number;
|
|
114
|
+
/** The alias, or the parameter's annotation, as written up to its first line break. */
|
|
115
|
+
readonly raw: string;
|
|
116
|
+
readonly reason: string;
|
|
117
|
+
};
|
|
118
|
+
/**
|
|
119
|
+
* The props-declaration violations found in one file.
|
|
120
|
+
*
|
|
121
|
+
* @since 0.15.0
|
|
122
|
+
*/
|
|
123
|
+
export type PropsFileViolations = {
|
|
124
|
+
readonly relativePath: string;
|
|
125
|
+
readonly violations: Array<PropsViolation>;
|
|
126
|
+
};
|
|
127
|
+
/**
|
|
128
|
+
* Outcome of one `audit props` run.
|
|
129
|
+
*
|
|
130
|
+
* @since 0.15.0
|
|
131
|
+
*/
|
|
132
|
+
export type PropsAuditResult = {
|
|
133
|
+
readonly files: Array<PropsFileViolations>;
|
|
134
|
+
readonly violationCount: number;
|
|
135
|
+
readonly allowlistedCount: number;
|
|
136
|
+
readonly scannedFileCount: number;
|
|
137
|
+
};
|
|
107
138
|
/**
|
|
108
139
|
* A `token()`, `tag()` or module display name that breaks the display-name convention.
|
|
109
140
|
*
|
|
@@ -297,4 +328,67 @@ export type LayersAuditResult = {
|
|
|
297
328
|
readonly allowlistedCount: number;
|
|
298
329
|
readonly scannedFileCount: number;
|
|
299
330
|
readonly packageCount: number;
|
|
331
|
+
};
|
|
332
|
+
/**
|
|
333
|
+
* A workspace package's `engines.node` floor.
|
|
334
|
+
*
|
|
335
|
+
* @since 0.15.0
|
|
336
|
+
*/
|
|
337
|
+
export type PackageEngineFloor = {
|
|
338
|
+
readonly packageName: string;
|
|
339
|
+
/** Repo-relative POSIX path of the package directory. */
|
|
340
|
+
readonly directory: string;
|
|
341
|
+
/** The floor as `X.Y.Z`. */
|
|
342
|
+
readonly floor: string;
|
|
343
|
+
};
|
|
344
|
+
/**
|
|
345
|
+
* A package whose Node floor breaks a rule a consumer or CI depends on.
|
|
346
|
+
*
|
|
347
|
+
* @since 0.15.0
|
|
348
|
+
*/
|
|
349
|
+
export type EngineViolation = {
|
|
350
|
+
readonly kind: "missing-floor";
|
|
351
|
+
readonly packageName: string;
|
|
352
|
+
} | {
|
|
353
|
+
readonly kind: "unparsable-floor";
|
|
354
|
+
readonly packageName: string;
|
|
355
|
+
readonly range: string;
|
|
356
|
+
} | {
|
|
357
|
+
readonly kind: "outside-dependency-engines";
|
|
358
|
+
readonly packageName: string;
|
|
359
|
+
readonly floor: string;
|
|
360
|
+
readonly dependency: string;
|
|
361
|
+
/** The manifest field that lists the dependency. */
|
|
362
|
+
readonly field: string;
|
|
363
|
+
/** The dependency's own `engines.node`. */
|
|
364
|
+
readonly range: string;
|
|
365
|
+
/** The releases the floor claims that `range` leaves out, as semver ranges joined by `||`. */
|
|
366
|
+
readonly uncovered: string;
|
|
367
|
+
} | {
|
|
368
|
+
readonly kind: "root-outside-dependency-engines";
|
|
369
|
+
/** The workspace root's name. */
|
|
370
|
+
readonly packageName: string;
|
|
371
|
+
readonly floor: string;
|
|
372
|
+
readonly dependency: string;
|
|
373
|
+
/** The dependency's own `engines.node`. */
|
|
374
|
+
readonly range: string;
|
|
375
|
+
/** The workspace packages that install the dependency at this range. */
|
|
376
|
+
readonly dependents: Array<string>;
|
|
377
|
+
/** The releases the root floor claims that `range` leaves out, as semver ranges joined by `||`. */
|
|
378
|
+
readonly uncovered: string;
|
|
379
|
+
} | {
|
|
380
|
+
readonly kind: "types-off-floor";
|
|
381
|
+
readonly packageName: string;
|
|
382
|
+
readonly floor: string;
|
|
383
|
+
readonly typesVersion: string;
|
|
384
|
+
};
|
|
385
|
+
/**
|
|
386
|
+
* Outcome of one `audit engines` run.
|
|
387
|
+
*
|
|
388
|
+
* @since 0.15.0
|
|
389
|
+
*/
|
|
390
|
+
export type EnginesAuditResult = {
|
|
391
|
+
readonly floors: Array<PackageEngineFloor>;
|
|
392
|
+
readonly violations: Array<EngineViolation>;
|
|
393
|
+
readonly packageCount: number;
|
|
300
394
|
};
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import type { EnginesAuditResult } from "#audit/domain/types";
|
|
2
|
+
/**
|
|
3
|
+
* Exit `1` when any Node floor breaks a rule.
|
|
4
|
+
*
|
|
5
|
+
* @since 0.15.0
|
|
6
|
+
*/
|
|
7
|
+
export declare function exitCodeForEnginesAuditResult(result: EnginesAuditResult): number;
|
|
8
|
+
/**
|
|
9
|
+
* Machine-readable engines audit summary for `--json`, which lists every floor so CI can plan one leg per floor.
|
|
10
|
+
*
|
|
11
|
+
* @since 0.15.0
|
|
12
|
+
*/
|
|
13
|
+
export declare function formatEnginesAuditJsonOutput(result: EnginesAuditResult, rootDir: string): string;
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { CLI_EXIT_GENERAL_ERROR, CLI_EXIT_SUCCESS } from "#core/exit-codes";
|
|
2
|
+
/**
|
|
3
|
+
* Exit `1` when any Node floor breaks a rule.
|
|
4
|
+
*
|
|
5
|
+
* @since 0.15.0
|
|
6
|
+
*/
|
|
7
|
+
export function exitCodeForEnginesAuditResult(result) {
|
|
8
|
+
return result.violations.length === 0 ? CLI_EXIT_SUCCESS : CLI_EXIT_GENERAL_ERROR;
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* Machine-readable engines audit summary for `--json`, which lists every floor so CI can plan one leg per floor.
|
|
12
|
+
*
|
|
13
|
+
* @since 0.15.0
|
|
14
|
+
*/
|
|
15
|
+
export function formatEnginesAuditJsonOutput(result, rootDir) {
|
|
16
|
+
return JSON.stringify({
|
|
17
|
+
schemaVersion: 1,
|
|
18
|
+
ok: result.violations.length === 0,
|
|
19
|
+
cwd: rootDir,
|
|
20
|
+
result,
|
|
21
|
+
});
|
|
22
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import * as z from "zod";
|
|
2
|
+
/**
|
|
3
|
+
* Resolved request for a single engines audit run.
|
|
4
|
+
*
|
|
5
|
+
* @since 0.15.0
|
|
6
|
+
*/
|
|
7
|
+
export type EnginesAuditRunRequest = {
|
|
8
|
+
readonly rootDir: string;
|
|
9
|
+
readonly targetPath: string;
|
|
10
|
+
readonly allowlist?: ReadonlyArray<string> | undefined;
|
|
11
|
+
readonly json: boolean;
|
|
12
|
+
};
|
|
13
|
+
/**
|
|
14
|
+
* Zod schema for {@link EnginesAuditRunRequest}.
|
|
15
|
+
*
|
|
16
|
+
* @since 0.15.0
|
|
17
|
+
*/
|
|
18
|
+
export declare const enginesAuditRunRequestSchema: z.ZodType<EnginesAuditRunRequest>;
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import * as z from "zod";
|
|
2
|
+
/**
|
|
3
|
+
* Zod schema for {@link EnginesAuditRunRequest}.
|
|
4
|
+
*
|
|
5
|
+
* @since 0.15.0
|
|
6
|
+
*/
|
|
7
|
+
export const enginesAuditRunRequestSchema = z.object({
|
|
8
|
+
rootDir: z.string().min(1),
|
|
9
|
+
targetPath: z.string().min(1),
|
|
10
|
+
allowlist: z.array(z.string()).optional(),
|
|
11
|
+
json: z.boolean(),
|
|
12
|
+
});
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/** Parses and compares the Node versions an `engines.node` floor and a resolved `@types/node` name. */
|
|
2
|
+
/**
|
|
3
|
+
* A Node release as its major, minor and patch numbers.
|
|
4
|
+
*
|
|
5
|
+
* @since 0.15.0
|
|
6
|
+
*/
|
|
7
|
+
export type NodeVersion = readonly [major: number, minor: number, patch: number];
|
|
8
|
+
/**
|
|
9
|
+
* Parses an `engines.node` range written as `>=X.Y.Z`, or returns `null` for any other form.
|
|
10
|
+
*
|
|
11
|
+
* @remarks A floor is the one bound a package promises, so a range with an upper bound or a wildcard is refused
|
|
12
|
+
* rather than approximated.
|
|
13
|
+
*
|
|
14
|
+
* @since 0.15.0
|
|
15
|
+
*/
|
|
16
|
+
export declare function parseNodeFloor(range: string): NodeVersion | null;
|
|
17
|
+
/**
|
|
18
|
+
* Parses a resolved version such as `24.0.15`, ignoring any peer suffix the lockfile appends, or returns `null`.
|
|
19
|
+
*
|
|
20
|
+
* @since 0.15.0
|
|
21
|
+
*/
|
|
22
|
+
export declare function parseNodeVersion(version: string): NodeVersion | null;
|
|
23
|
+
/**
|
|
24
|
+
* Whether `@types/node` at this version declares nothing the floor lacks — the floor's major, at a minor no newer.
|
|
25
|
+
*
|
|
26
|
+
* @since 0.15.0
|
|
27
|
+
*/
|
|
28
|
+
export declare function typesFitFloor(types: NodeVersion, floor: NodeVersion): boolean;
|
|
29
|
+
/**
|
|
30
|
+
* Formats a version as `X.Y.Z`.
|
|
31
|
+
*
|
|
32
|
+
* @since 0.15.0
|
|
33
|
+
*/
|
|
34
|
+
export declare function formatNodeVersion(version: NodeVersion): string;
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/** Parses and compares the Node versions an `engines.node` floor and a resolved `@types/node` name. */
|
|
2
|
+
const floorPattern = /^>=\s*(\d+)\.(\d+)\.(\d+)$/;
|
|
3
|
+
const versionPattern = /^(\d+)\.(\d+)\.(\d+)/;
|
|
4
|
+
/**
|
|
5
|
+
* Parses an `engines.node` range written as `>=X.Y.Z`, or returns `null` for any other form.
|
|
6
|
+
*
|
|
7
|
+
* @remarks A floor is the one bound a package promises, so a range with an upper bound or a wildcard is refused
|
|
8
|
+
* rather than approximated.
|
|
9
|
+
*
|
|
10
|
+
* @since 0.15.0
|
|
11
|
+
*/
|
|
12
|
+
export function parseNodeFloor(range) {
|
|
13
|
+
const match = floorPattern.exec(range.trim());
|
|
14
|
+
return match === null ? null : [Number(match[1]), Number(match[2]), Number(match[3])];
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Parses a resolved version such as `24.0.15`, ignoring any peer suffix the lockfile appends, or returns `null`.
|
|
18
|
+
*
|
|
19
|
+
* @since 0.15.0
|
|
20
|
+
*/
|
|
21
|
+
export function parseNodeVersion(version) {
|
|
22
|
+
const match = versionPattern.exec(version.trim());
|
|
23
|
+
return match === null ? null : [Number(match[1]), Number(match[2]), Number(match[3])];
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Whether `@types/node` at this version declares nothing the floor lacks — the floor's major, at a minor no newer.
|
|
27
|
+
*
|
|
28
|
+
* @since 0.15.0
|
|
29
|
+
*/
|
|
30
|
+
export function typesFitFloor(types, floor) {
|
|
31
|
+
return types[0] === floor[0] && types[1] <= floor[1];
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Formats a version as `X.Y.Z`.
|
|
35
|
+
*
|
|
36
|
+
* @since 0.15.0
|
|
37
|
+
*/
|
|
38
|
+
export function formatNodeVersion(version) {
|
|
39
|
+
return version.join(".");
|
|
40
|
+
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/** Finds the Node releases at or above a floor that an `engines.node` range leaves out. */
|
|
2
|
+
import type { NodeVersion } from "#audit/engines/domain/node-floor";
|
|
3
|
+
/**
|
|
4
|
+
* Lists the odd majors between the floor's and the newest tested one, which reach end-of-life without becoming LTS.
|
|
5
|
+
*
|
|
6
|
+
* @remarks The floor's own line and every line from the newest tested major up stay judged, since a package still
|
|
7
|
+
* claims those; with no newest release known, every line does.
|
|
8
|
+
*
|
|
9
|
+
* @since 0.15.0
|
|
10
|
+
*/
|
|
11
|
+
export declare function shortLivedMajors(floor: NodeVersion, newest: NodeVersion | null): Array<number>;
|
|
12
|
+
/**
|
|
13
|
+
* Lists the sub-ranges of `>=floor` that `range` does not admit, each written as a semver range, or returns `null` when
|
|
14
|
+
* no semver parser reads `range`.
|
|
15
|
+
*
|
|
16
|
+
* @remarks Releases on the `unjudged` majors never count as left out. Node publishes no prereleases on a release line,
|
|
17
|
+
* so a prerelease bound such as the `<23.0.0-0` a caret expands to is read as the release it precedes.
|
|
18
|
+
*
|
|
19
|
+
* @since 0.15.0
|
|
20
|
+
*/
|
|
21
|
+
export declare function uncoveredNodeRanges(floor: NodeVersion, range: string, unjudged?: ReadonlyArray<number>): Array<string> | null;
|