@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.
Files changed (40) hide show
  1. package/CHANGELOG.md +51 -0
  2. package/README.md +70 -5
  3. package/dist/arrange/simplify/variant-classname-probe.js +2 -11
  4. package/dist/audit/command.js +40 -0
  5. package/dist/audit/comments/domain/comment-dividers.js +8 -1
  6. package/dist/audit/display-names/domain/display-names.js +4 -3
  7. package/dist/audit/domain/types.d.ts +94 -0
  8. package/dist/audit/engines/cli-result.d.ts +13 -0
  9. package/dist/audit/engines/cli-result.js +22 -0
  10. package/dist/audit/engines/cli-schema.d.ts +18 -0
  11. package/dist/audit/engines/cli-schema.js +12 -0
  12. package/dist/audit/engines/domain/node-floor.d.ts +34 -0
  13. package/dist/audit/engines/domain/node-floor.js +40 -0
  14. package/dist/audit/engines/domain/range-gaps.d.ts +21 -0
  15. package/dist/audit/engines/domain/range-gaps.js +136 -0
  16. package/dist/audit/engines/output.d.ts +7 -0
  17. package/dist/audit/engines/output.js +40 -0
  18. package/dist/audit/engines/prepare.d.ts +16 -0
  19. package/dist/audit/engines/prepare.js +12 -0
  20. package/dist/audit/engines/run.d.ts +18 -0
  21. package/dist/audit/engines/run.js +225 -0
  22. package/dist/audit/props/cli-result.d.ts +13 -0
  23. package/dist/audit/props/cli-result.js +22 -0
  24. package/dist/audit/props/cli-schema.d.ts +18 -0
  25. package/dist/audit/props/cli-schema.js +12 -0
  26. package/dist/audit/props/domain/props-intersection.d.ts +56 -0
  27. package/dist/audit/props/domain/props-intersection.js +189 -0
  28. package/dist/audit/props/output.d.ts +7 -0
  29. package/dist/audit/props/output.js +21 -0
  30. package/dist/audit/props/prepare.d.ts +13 -0
  31. package/dist/audit/props/prepare.js +9 -0
  32. package/dist/audit/props/run.d.ts +17 -0
  33. package/dist/audit/props/run.js +57 -0
  34. package/dist/audit/props/type-probe.d.ts +23 -0
  35. package/dist/audit/props/type-probe.js +85 -0
  36. package/dist/core/config/schema.d.ts +1 -0
  37. package/dist/core/config/schema.js +1 -0
  38. package/dist/core/type-server.d.ts +21 -0
  39. package/dist/core/type-server.js +32 -0
  40. 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 ≥ 24** (the CLI is published as ESM).
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 publish` are general-purpose — they work for any pnpm workspace or single package that builds
155
- with `tsc`. The other four audits encode codefast's own house style (logical Tailwind directions, named React imports, a
156
- specific comment/divider grammar, a `namespace:Name` scheme for `@codefast/di` tokens). Adopt them if they fit your
157
- project; otherwise skip them, or use an allowlist to narrow their scope.
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 { AppError, messageFrom } from "#core/errors";
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 {
@@ -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 = line.trimStart().startsWith("/*") && !line.includes("*/");
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, whose first argument is a string literal.
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*(?:<(?:[^<>]|<(?:[^<>]|<(?:[^<>]|<[^<>]*>)*>)*>)*>)?|((?:Sync|Async)?Module)\s*\.\s*create(?:Async)?)\s*\(\s*(["'])((?:(?!\3)[^\\\n]|\\.)*)\3(\s*\))?/g;
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[4]);
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;