@codefast/cli 0.13.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 (72) hide show
  1. package/CHANGELOG.md +80 -0
  2. package/README.md +124 -40
  3. package/dist/arrange/simplify/variant-classname-probe.js +2 -11
  4. package/dist/audit/command.js +57 -16
  5. package/dist/audit/comments/domain/comment-content.d.ts +12 -0
  6. package/dist/audit/comments/domain/comment-content.js +17 -4
  7. package/dist/audit/comments/domain/comment-dividers.js +8 -1
  8. package/dist/audit/display-names/domain/display-names.js +4 -3
  9. package/dist/audit/domain/types.d.ts +119 -24
  10. package/dist/audit/engines/cli-result.d.ts +13 -0
  11. package/dist/audit/engines/cli-result.js +22 -0
  12. package/dist/audit/engines/cli-schema.d.ts +18 -0
  13. package/dist/audit/{constants → engines}/cli-schema.js +3 -3
  14. package/dist/audit/engines/domain/node-floor.d.ts +34 -0
  15. package/dist/audit/engines/domain/node-floor.js +40 -0
  16. package/dist/audit/engines/domain/range-gaps.d.ts +21 -0
  17. package/dist/audit/engines/domain/range-gaps.js +136 -0
  18. package/dist/audit/engines/output.d.ts +7 -0
  19. package/dist/audit/engines/output.js +40 -0
  20. package/dist/audit/engines/prepare.d.ts +16 -0
  21. package/dist/audit/engines/prepare.js +12 -0
  22. package/dist/audit/engines/run.d.ts +18 -0
  23. package/dist/audit/engines/run.js +225 -0
  24. package/dist/audit/layers/cli-result.d.ts +13 -0
  25. package/dist/audit/{constants → layers}/cli-result.js +6 -6
  26. package/dist/audit/layers/cli-schema.d.ts +29 -0
  27. package/dist/audit/layers/cli-schema.js +17 -0
  28. package/dist/audit/layers/domain/layering.d.ts +46 -0
  29. package/dist/audit/layers/domain/layering.js +191 -0
  30. package/dist/audit/layers/output.d.ts +7 -0
  31. package/dist/audit/layers/output.js +21 -0
  32. package/dist/audit/layers/prepare.d.ts +25 -0
  33. package/dist/audit/layers/prepare.js +66 -0
  34. package/dist/audit/layers/run.d.ts +19 -0
  35. package/dist/audit/layers/run.js +62 -0
  36. package/dist/audit/prepare.d.ts +13 -1
  37. package/dist/audit/prepare.js +16 -1
  38. package/dist/audit/props/cli-result.d.ts +13 -0
  39. package/dist/audit/props/cli-result.js +22 -0
  40. package/dist/audit/props/cli-schema.d.ts +18 -0
  41. package/dist/audit/props/cli-schema.js +12 -0
  42. package/dist/audit/props/domain/props-intersection.d.ts +56 -0
  43. package/dist/audit/props/domain/props-intersection.js +189 -0
  44. package/dist/audit/props/output.d.ts +7 -0
  45. package/dist/audit/{constants → props}/output.js +5 -5
  46. package/dist/audit/props/prepare.d.ts +13 -0
  47. package/dist/audit/props/prepare.js +9 -0
  48. package/dist/audit/props/run.d.ts +17 -0
  49. package/dist/audit/props/run.js +57 -0
  50. package/dist/audit/props/type-probe.d.ts +23 -0
  51. package/dist/audit/props/type-probe.js +85 -0
  52. package/dist/core/config/schema.d.ts +13 -4
  53. package/dist/core/config/schema.js +14 -1
  54. package/dist/core/type-server.d.ts +21 -0
  55. package/dist/core/type-server.js +32 -0
  56. package/dist/tag/cli-result.d.ts +3 -0
  57. package/dist/tag/cli-result.js +8 -2
  58. package/dist/tag/domain/types.d.ts +15 -0
  59. package/dist/tag/output.js +13 -6
  60. package/dist/tag/run.js +2 -0
  61. package/dist/tag/writer/since-writer.d.ts +5 -0
  62. package/dist/tag/writer/since-writer.js +41 -9
  63. package/package.json +6 -5
  64. package/dist/audit/constants/cli-result.d.ts +0 -13
  65. package/dist/audit/constants/cli-schema.d.ts +0 -18
  66. package/dist/audit/constants/domain/constants.d.ts +0 -8
  67. package/dist/audit/constants/domain/constants.js +0 -66
  68. package/dist/audit/constants/output.d.ts +0 -7
  69. package/dist/audit/constants/prepare.d.ts +0 -16
  70. package/dist/audit/constants/prepare.js +0 -37
  71. package/dist/audit/constants/run.d.ts +0 -14
  72. package/dist/audit/constants/run.js +0 -64
package/CHANGELOG.md CHANGED
@@ -1,5 +1,85 @@
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
+
54
+ ## 0.14.0
55
+
56
+ ### Minor Changes
57
+
58
+ - [#1007](https://github.com/codefastlabs/codefast/pull/1007) Add `codefast audit layers`, which holds a package's `src/` to the layering its architecture states.
59
+ `audit.layers.packages` lists each package's layers bottom to top, every entry a family directly under the root — a
60
+ directory, or a lone module sitting flat — and the audit reports every value import or re-export that points up the
61
+ list, plus every module no layer places. Type-only imports pass whichever way they point; a dynamic `import()` counts as
62
+ a value import. A configured name the workspace does not hold, an entry nested below the root, and a family placed twice
63
+ are refused before anything is scanned. `audit.layers.allowlist` takes the offending import as written, or
64
+ `path:<import>`.
65
+
66
+ - [#990](https://github.com/codefastlabs/codefast/pull/990) Remove `codefast audit constants`, the audit that required every upper-case numeric `const` to name its kind in the
67
+ comment above it.
68
+
69
+ Breaking: the `audit constants` subcommand is gone, and `audit.constants` is no longer a config key, so a
70
+ `codefast.config` that still sets it fails validation as an unknown key; delete that section.
71
+
72
+ - [#992](https://github.com/codefastlabs/codefast/pull/992) `codefast tag` stamps every overload signature again, each in its own doc block. Since the move to `oxc-parser` it
73
+ stamped only an overloaded function's implementation, the one signature a `.d.ts` drops, so a released overload reached
74
+ consumers with no `@since` on any signature they can see.
75
+
76
+ A declaration with no doc block and a `//` comment on the line above it now fails the run instead of getting a fresh
77
+ block there, where the block would stack under a note (which `audit comments` rejects) or split a directive from the
78
+ code it governs. The run names each such declaration by file and line, lists it under `blockedDeclarations` in `--json`,
79
+ leaves its file untouched, and exits `1`: once a release ships the declaration unstamped, a later run can only stamp a
80
+ version that did not introduce it. The `--json` `ok` field now follows the exit code, so a failed target also reports
81
+ `ok: false`.
82
+
3
83
  ## 0.13.0
4
84
 
5
85
  ### 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
@@ -111,9 +111,11 @@ codefast # Codefast monorepo developer CLI
111
111
  │ ├─ links [target] # markdown links pointing at a missing path/anchor
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
- │ ├─ constants [target] # numeric constants whose comment names none of the three kinds
115
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)
116
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
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)
119
121
  │ (each audit also takes [target] + --json)
@@ -145,16 +147,19 @@ Every command also responds to `--help`; each command's section below explains w
145
147
  | `audit links` | Report markdown cross-references that resolve to nothing | no |
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
- | `audit constants` | Require every tuned numeric constant to name the kind of number it is | no |
149
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 |
150
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 |
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
- **Which of these are for you?** `arrange`, `mirror`, `pack-slim`, `tag`, `audit links`, `audit assertions`, and
154
- `audit publish` are general-purpose — they work for any pnpm workspace or single package that builds with `tsc`. The
155
- other five audits encode codefast's own house style (logical Tailwind directions, named React imports, a specific
156
- comment/divider grammar, a `namespace:Name` scheme for `@codefast/di` tokens, a named kind for every tuned numeric
157
- constant). Adopt them if they fit your project; otherwise skip them, or use an allowlist to narrow their scope.
157
+ **Which of these are for you?** `arrange`, `mirror`, `pack-slim`, `tag`, `audit links`, `audit assertions`,
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
 
@@ -276,9 +281,15 @@ Exits `1` when any package fails, `0` otherwise.
276
281
  ## `tag`
277
282
 
278
283
  Adds `@since <version>` tags to the doc comments of exported declarations that lack one, creating the doc block when
279
- there is none. The version comes from the nearest `package.json` above each target file, and declarations that already
280
- carry `@since` are left alone. Run it at release time so published APIs carry accurate version metadata — never
281
- hand-write `@since`.
284
+ there is none. Overload signatures are declarations too, each stamped on its own, because the `.d.ts` keeps every
285
+ overload's doc block and drops the implementation's. The version comes from the nearest `package.json` above each target
286
+ file, and declarations that already carry `@since` are left alone. Run it at release time so published APIs carry
287
+ accurate version metadata — never hand-write `@since`.
288
+
289
+ A declaration with no doc block and a `//` comment on the line above it is reported instead: a block written there would
290
+ stack under a note, which `audit comments` rejects, or split a directive from the code it governs. Its file is left as
291
+ it is, so every reported line stays accurate. Write the doc block by hand before the release that ships the declaration,
292
+ since a later run can only stamp a version that did not introduce it.
282
293
 
283
294
  ```bash
284
295
  codefast tag # auto-discover packages from cwd (or the single package)
@@ -286,7 +297,8 @@ codefast tag packages/ui/src # tag one directory or file
286
297
  codefast tag --dry-run # summary only, no writes
287
298
  ```
288
299
 
289
- Exits `1` when no target is selected, when any target fails, or when the `tag.onAfterWrite` hook fails.
300
+ Exits `1` when no target is selected, when any target fails, when a declaration is left unstamped, or when the
301
+ `tag.onAfterWrite` hook fails.
290
302
 
291
303
  ## `audit`
292
304
 
@@ -366,6 +378,35 @@ codefast audit assertions --json # machine-readable summary
366
378
  Configure exceptions via `audit.assertions.allowlist` — each entry is the assertion as written or
367
379
  `repo/relative/path.ts:<assertion>` — though the inline directive keeps the reason beside the code it excuses.
368
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
+
369
410
  ### `audit publish`
370
411
 
371
412
  Reports what would break a consumer's install of a published package, while it can still be fixed:
@@ -385,6 +426,71 @@ codefast audit publish # every published package in the work
385
426
  codefast audit publish --json # machine-readable summary
386
427
  ```
387
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
+
459
+ ### `audit layers`
460
+
461
+ _General-purpose._ Holds a package's `src/` to the layering its architecture states. You list the layers in
462
+ configuration, bottom to top, each naming the families directly under the root — a directory, or a lone module sitting
463
+ flat (`errors.ts`) — and the audit reports every value import or re-export that points up the list, plus every module no
464
+ layer places. Type-only imports erase at build time and couple nothing, so they may point anywhere; a dynamic `import()`
465
+ counts as a value import wherever it sits.
466
+
467
+ ```js
468
+ // codefast.config.js
469
+ export default {
470
+ audit: {
471
+ layers: {
472
+ packages: {
473
+ "@acme/di": {
474
+ root: "src", // where the layers sit, relative to the package (default)
475
+ layers: [["core", "errors.ts"], ["engine"], ["container"], ["index.ts"]],
476
+ },
477
+ },
478
+ allowlist: [],
479
+ },
480
+ },
481
+ };
482
+ ```
483
+
484
+ ```bash
485
+ codefast audit layers # every package audit.layers.packages names
486
+ codefast audit layers packages/di # one package, or a directory beneath its root
487
+ codefast audit layers --json # machine-readable summary
488
+ ```
489
+
490
+ A configured package name the workspace does not hold, a layer entry nested below the root, and a family placed twice
491
+ are refused before anything is scanned. Configure exceptions via `audit.layers.allowlist` — each entry is the offending
492
+ import as written or `repo/relative/path.ts:<import>`.
493
+
388
494
  ### `audit comments`
389
495
 
390
496
  _House style._ Checks doc-comment conventions. Section dividers not in the one allowed form are mechanical, so `--fix`
@@ -420,30 +526,6 @@ codefast audit display-names --json # machine-readable summary
420
526
  Configure exceptions via `audit.displayNames.allowlist` — each entry is the call as written, through its closing quote
421
527
  (or parenthesis when the name is the only argument), or `repo/relative/path.ts:<call>`.
422
528
 
423
- ### `audit constants`
424
-
425
- _House style._ Holds library sources to one rule for tuned numbers: a numeric constant says which kind of number it is.
426
- It flags an upper-case `const NAME = <number>` in a `.ts`/`.tsx` file under a `src` directory — tests, benchmarks, apps,
427
- and examples are out of scope — unless the comment directly above it, a `/* … */` block or a run of `//` lines, names
428
- one of three kinds:
429
-
430
- - `a constant of the machine` — a width of the platform the code runs on;
431
- - `a value the contract fixes` — a number the documented contract promises;
432
- - `derived from bind-time data` — a figure computed from what a caller hands in.
433
-
434
- A count that merely looks reasonable is none of them, so it is reported. `0`, `1`, and `-1` are skipped: they stand for
435
- absence or identity, not for a tuned size.
436
-
437
- ```bash
438
- codefast audit constants # uses audit.constants.target from config
439
- codefast audit constants packages/di/src # explicit target
440
- codefast audit constants --json # machine-readable summary
441
- ```
442
-
443
- With no `[target]`, the scan root is `audit.constants.target` from the config; when neither is set the command fails.
444
- Configure exceptions via `audit.constants.allowlist` — each entry is the constant's name or `repo/relative/path.ts:NAME`
445
- — for a measured policy that has to stay a tuned number.
446
-
447
529
  ## Configuration
448
530
 
449
531
  **You do not need a config file.** Every command has sensible defaults and works with none. Add a `codefast.config.*`
@@ -579,9 +661,10 @@ export default {
579
661
  imports: { allowlist: [] }, // offending import text as written, or `repo/relative/path.tsx:<text>`
580
662
  assertions: { allowlist: [] }, // assertion as written, or `repo/relative/path.ts:<assertion>`
581
663
  displayNames: { allowlist: [] }, // call as written, or `repo/relative/path.ts:<call>`
582
- constants: {
583
- target: "packages/core/src", // default scan root when no CLI arg is passed
584
- allowlist: [], // constant name, or `repo/relative/path.ts:NAME`
664
+ layers: {
665
+ // per package: its layers bottom to top, each entry a directory or module file under `root` (default `src`)
666
+ packages: { "@acme/di": { layers: [["core", "errors.ts"], ["engine"], ["index.ts"]] } },
667
+ allowlist: [], // import as written, or `repo/relative/path.ts:<import>`
585
668
  },
586
669
  },
587
670
  };
@@ -635,8 +718,9 @@ pnpm run cli:audit:comments # codefast audit comments
635
718
  pnpm run cli:audit:imports # codefast audit imports
636
719
  pnpm run cli:audit:assertions # codefast audit assertions
637
720
  pnpm run cli:audit:display-names # codefast audit display-names
638
- pnpm run cli:audit:constants # codefast audit constants
721
+ pnpm run cli:audit:layers # codefast audit layers
639
722
  pnpm run cli:audit:publish # codefast audit publish
723
+ pnpm run cli:audit:engines # codefast audit engines
640
724
  ```
641
725
 
642
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 {
@@ -9,26 +9,36 @@ import { commentAuditRunRequestSchema } from "#audit/comments/cli-schema";
9
9
  import { presentCommentAuditResult } from "#audit/comments/output";
10
10
  import { prepareCommentAudit } from "#audit/comments/prepare";
11
11
  import { runCommentAudit } from "#audit/comments/run";
12
- import { exitCodeForConstantAuditResult, formatConstantAuditJsonOutput } from "#audit/constants/cli-result";
13
- import { constantAuditRunRequestSchema } from "#audit/constants/cli-schema";
14
- import { presentConstantAuditResult } from "#audit/constants/output";
15
- import { prepareConstantAudit } from "#audit/constants/prepare";
16
- import { runConstantAudit } from "#audit/constants/run";
17
12
  import { exitCodeForDisplayNameAuditResult, formatDisplayNameAuditJsonOutput } from "#audit/display-names/cli-result";
18
13
  import { displayNameAuditRunRequestSchema } from "#audit/display-names/cli-schema";
19
14
  import { presentDisplayNameAuditResult } from "#audit/display-names/output";
20
15
  import { prepareDisplayNameAudit } from "#audit/display-names/prepare";
21
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";
22
22
  import { exitCodeForImportsAuditResult, formatImportsAuditJsonOutput } from "#audit/imports/cli-result";
23
23
  import { importsAuditRunRequestSchema } from "#audit/imports/cli-schema";
24
24
  import { presentImportsAuditResult } from "#audit/imports/output";
25
25
  import { prepareImportsAudit } from "#audit/imports/prepare";
26
26
  import { runImportsAudit } from "#audit/imports/run";
27
+ import { exitCodeForLayersAuditResult, formatLayersAuditJsonOutput } from "#audit/layers/cli-result";
28
+ import { layersAuditRunRequestSchema } from "#audit/layers/cli-schema";
29
+ import { presentLayersAuditResult } from "#audit/layers/output";
30
+ import { prepareLayersAudit } from "#audit/layers/prepare";
31
+ import { runLayersAudit } from "#audit/layers/run";
27
32
  import { exitCodeForLinkAuditResult, formatLinkAuditJsonOutput } from "#audit/links/cli-result";
28
33
  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,21 +131,21 @@ const displayNamesCheck = {
121
131
  formatJson: formatDisplayNameAuditJsonOutput,
122
132
  exitCode: exitCodeForDisplayNameAuditResult,
123
133
  };
124
- const constantsCheck = {
125
- name: "constants",
126
- description: "Report numeric constants whose comment names none of the three kinds a number may be",
127
- targetHelp: "Directory or file to scan (default: audit.constants.target from config)",
128
- schema: constantAuditRunRequestSchema,
129
- prepare: prepareConstantAudit,
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,
130
140
  buildRequest: baseAuditRequest,
131
- run: (fs, request) => runConstantAudit(fs, {
141
+ run: (fs, request) => runPropsAudit(fs, {
132
142
  rootDir: request.rootDir,
133
143
  targetPath: request.targetPath,
134
144
  allowlist: request.allowlist ?? [],
135
145
  }),
136
- present: presentConstantAuditResult,
137
- formatJson: formatConstantAuditJsonOutput,
138
- exitCode: exitCodeForConstantAuditResult,
146
+ present: presentPropsAuditResult,
147
+ formatJson: formatPropsAuditJsonOutput,
148
+ exitCode: exitCodeForPropsAuditResult,
139
149
  };
140
150
  const commentsCheck = {
141
151
  name: "comments",
@@ -157,6 +167,23 @@ const commentsCheck = {
157
167
  command.option("--fix", "Rewrite every mechanically fixable divider in place", false);
158
168
  },
159
169
  };
170
+ const layersCheck = {
171
+ name: "layers",
172
+ description: "Report value imports that point up a package's configured layers, and modules sitting in no layer",
173
+ targetHelp: "Directory or file to scan (default: the repo root, reaching every package audit.layers names)",
174
+ schema: layersAuditRunRequestSchema,
175
+ prepare: prepareLayersAudit,
176
+ buildRequest: (prelude, opts) => ({ ...baseAuditRequest(prelude, opts), packages: prelude.packages }),
177
+ run: (fs, request) => runLayersAudit(fs, {
178
+ rootDir: request.rootDir,
179
+ targetPath: request.targetPath,
180
+ allowlist: request.allowlist ?? [],
181
+ packages: request.packages,
182
+ }),
183
+ present: presentLayersAuditResult,
184
+ formatJson: formatLayersAuditJsonOutput,
185
+ exitCode: exitCodeForLayersAuditResult,
186
+ };
160
187
  const publishCheck = {
161
188
  name: "publish",
162
189
  description: "Report what breaks a consumer's install: #/ imports, unshipped exports/imports targets, and stylesheet @source paths reaching nothing shipped",
@@ -169,6 +196,18 @@ const publishCheck = {
169
196
  formatJson: formatPublishAuditJsonOutput,
170
197
  exitCode: exitCodeForPublishAuditResult,
171
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
+ };
172
211
  /**
173
212
  * Adapts an `AuditCheck` descriptor onto the shared command pipeline.
174
213
  */
@@ -200,8 +239,10 @@ export function createAuditCommand() {
200
239
  registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(importsCheck));
201
240
  registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(assertionsCheck));
202
241
  registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(displayNamesCheck));
203
- registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(constantsCheck));
242
+ registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(propsCheck));
204
243
  registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(commentsCheck));
244
+ registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(layersCheck));
205
245
  registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(publishCheck));
246
+ registerPipelineSubcommand(cmd, nodeFilesystem, auditCheckToPipeline(enginesCheck));
206
247
  return cmd;
207
248
  }
@@ -18,6 +18,18 @@ export interface CommentContentFinding {
18
18
  readonly raw: string;
19
19
  readonly defect: CommentContentDefectKind;
20
20
  }
21
+ /**
22
+ * Returns whether a line is a `//` note: a line comment that is neither a divider nor a tooling directive.
23
+ *
24
+ * @since 0.14.0
25
+ */
26
+ export declare function isNoteLine(line: string): boolean;
27
+ /**
28
+ * Returns whether a line is a `//` tooling directive, which governs the code below it.
29
+ *
30
+ * @since 0.14.0
31
+ */
32
+ export declare function isDirectiveLine(line: string): boolean;
21
33
  /**
22
34
  * Scans a source file's comments for banned content, in source order.
23
35
  *
@@ -18,6 +18,22 @@ const declarationPattern = /^[ \t]*(?:export|const|let|var|function|class|interf
18
18
  // A divider or a tooling directive above a doc block is not a stacked note.
19
19
  const dividerLinePattern = /^[ \t]*\/\/[ \t]*[-=─_*~#]{2,}/;
20
20
  const directiveLinePattern = /^[ \t]*\/\/[ \t]*(?:oxlint-|eslint-|@ts-|prettier-)/;
21
+ /**
22
+ * Returns whether a line is a `//` note: a line comment that is neither a divider nor a tooling directive.
23
+ *
24
+ * @since 0.14.0
25
+ */
26
+ export function isNoteLine(line) {
27
+ return lineCommentPattern.test(line) && !dividerLinePattern.test(line) && !isDirectiveLine(line);
28
+ }
29
+ /**
30
+ * Returns whether a line is a `//` tooling directive, which governs the code below it.
31
+ *
32
+ * @since 0.14.0
33
+ */
34
+ export function isDirectiveLine(line) {
35
+ return directiveLinePattern.test(line);
36
+ }
21
37
  /**
22
38
  * Scans a source file's comments for banned content, in source order.
23
39
  *
@@ -37,10 +53,7 @@ export function scanCommentContent(content, language) {
37
53
  // A `//` run stacked directly above a doc block reads as a second doc — it belongs inside.
38
54
  if (language === "js" && !insideBlock && trimmed.startsWith("/**")) {
39
55
  let runStart = index;
40
- while (runStart > 0 &&
41
- lineCommentPattern.test(lines[runStart - 1]) &&
42
- !dividerLinePattern.test(lines[runStart - 1]) &&
43
- !directiveLinePattern.test(lines[runStart - 1])) {
56
+ while (runStart > 0 && isNoteLine(lines[runStart - 1])) {
44
57
  runStart--;
45
58
  }
46
59
  if (runStart < index) {
@@ -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
  }