@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
@@ -105,63 +105,63 @@ export type AssertionAuditResult = {
105
105
  readonly scannedFileCount: number;
106
106
  };
107
107
  /**
108
- * A `token()`, `tag()` or module display name that breaks the display-name convention.
108
+ * A component props type joined with `&` where an interface could extend every part, or whose parts do not resolve.
109
109
  *
110
- * @since 0.9.0
110
+ * @since 0.15.0
111
111
  */
112
- export type DisplayNameViolation = {
112
+ export type PropsViolation = {
113
113
  readonly line: number;
114
- /** The call as written, through its closing quote. */
114
+ /** The alias, or the parameter's annotation, as written up to its first line break. */
115
115
  readonly raw: string;
116
116
  readonly reason: string;
117
117
  };
118
118
  /**
119
- * The display-name violations found in one file.
119
+ * The props-declaration violations found in one file.
120
120
  *
121
- * @since 0.9.0
121
+ * @since 0.15.0
122
122
  */
123
- export type DisplayNameFileViolations = {
123
+ export type PropsFileViolations = {
124
124
  readonly relativePath: string;
125
- readonly violations: Array<DisplayNameViolation>;
125
+ readonly violations: Array<PropsViolation>;
126
126
  };
127
127
  /**
128
- * Outcome of one `audit display-names` run.
128
+ * Outcome of one `audit props` run.
129
129
  *
130
- * @since 0.9.0
130
+ * @since 0.15.0
131
131
  */
132
- export type DisplayNameAuditResult = {
133
- readonly files: Array<DisplayNameFileViolations>;
132
+ export type PropsAuditResult = {
133
+ readonly files: Array<PropsFileViolations>;
134
134
  readonly violationCount: number;
135
135
  readonly allowlistedCount: number;
136
136
  readonly scannedFileCount: number;
137
137
  };
138
138
  /**
139
- * A numeric constant whose comment names none of the three kinds.
139
+ * A `token()`, `tag()` or module display name that breaks the display-name convention.
140
140
  *
141
- * @since 0.11.0
141
+ * @since 0.9.0
142
142
  */
143
- export type ConstantViolation = {
143
+ export type DisplayNameViolation = {
144
144
  readonly line: number;
145
- /** The declaration's name and value, as `NAME = 32`. */
145
+ /** The call as written, through its closing quote. */
146
146
  readonly raw: string;
147
147
  readonly reason: string;
148
148
  };
149
149
  /**
150
- * The numeric-constant violations found in one file.
150
+ * The display-name violations found in one file.
151
151
  *
152
- * @since 0.11.0
152
+ * @since 0.9.0
153
153
  */
154
- export type ConstantFileViolations = {
154
+ export type DisplayNameFileViolations = {
155
155
  readonly relativePath: string;
156
- readonly violations: Array<ConstantViolation>;
156
+ readonly violations: Array<DisplayNameViolation>;
157
157
  };
158
158
  /**
159
- * Outcome of one `audit constants` run.
159
+ * Outcome of one `audit display-names` run.
160
160
  *
161
- * @since 0.11.0
161
+ * @since 0.9.0
162
162
  */
163
- export type ConstantAuditResult = {
164
- readonly files: Array<ConstantFileViolations>;
163
+ export type DisplayNameAuditResult = {
164
+ readonly files: Array<DisplayNameFileViolations>;
165
165
  readonly violationCount: number;
166
166
  readonly allowlistedCount: number;
167
167
  readonly scannedFileCount: number;
@@ -296,4 +296,99 @@ export type PublishAuditResult = {
296
296
  readonly legacyImportCount: number;
297
297
  readonly scannedFileCount: number;
298
298
  readonly packageCount: number;
299
+ };
300
+ /**
301
+ * A module outside every configured layer, or a value import that points up the layers.
302
+ *
303
+ * @since 0.14.0
304
+ */
305
+ export type LayerViolation = {
306
+ readonly line: number;
307
+ /** The import or re-export as written, or the module path when the module itself is unplaced. */
308
+ readonly raw: string;
309
+ readonly reason: string;
310
+ };
311
+ /**
312
+ * The layering violations found in one file.
313
+ *
314
+ * @since 0.14.0
315
+ */
316
+ export type LayerFileViolations = {
317
+ readonly relativePath: string;
318
+ readonly violations: Array<LayerViolation>;
319
+ };
320
+ /**
321
+ * Outcome of one `audit layers` run.
322
+ *
323
+ * @since 0.14.0
324
+ */
325
+ export type LayersAuditResult = {
326
+ readonly files: Array<LayerFileViolations>;
327
+ readonly violationCount: number;
328
+ readonly allowlistedCount: number;
329
+ readonly scannedFileCount: number;
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;
299
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>;
@@ -1,10 +1,10 @@
1
1
  import * as z from "zod";
2
2
  /**
3
- * Zod schema for {@link ConstantAuditRunRequest}.
3
+ * Zod schema for {@link EnginesAuditRunRequest}.
4
4
  *
5
- * @since 0.11.0
5
+ * @since 0.15.0
6
6
  */
7
- export const constantAuditRunRequestSchema = z.object({
7
+ export const enginesAuditRunRequestSchema = z.object({
8
8
  rootDir: z.string().min(1),
9
9
  targetPath: z.string().min(1),
10
10
  allowlist: z.array(z.string()).optional(),
@@ -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;
@@ -0,0 +1,136 @@
1
+ /** Finds the Node releases at or above a floor that an `engines.node` range leaves out. */
2
+ import { compare, Range, SemVer, validRange } from "semver";
3
+ import { formatNodeVersion } from "#audit/engines/domain/node-floor";
4
+ /**
5
+ * Lists the odd majors between the floor's and the newest tested one, which reach end-of-life without becoming LTS.
6
+ *
7
+ * @remarks The floor's own line and every line from the newest tested major up stay judged, since a package still
8
+ * claims those; with no newest release known, every line does.
9
+ *
10
+ * @since 0.15.0
11
+ */
12
+ export function shortLivedMajors(floor, newest) {
13
+ const majors = [];
14
+ for (let major = floor[0] + 1; newest !== null && major < newest[0]; major++) {
15
+ if (major % 2 === 1) {
16
+ majors.push(major);
17
+ }
18
+ }
19
+ return majors;
20
+ }
21
+ /**
22
+ * Lists the sub-ranges of `>=floor` that `range` does not admit, each written as a semver range, or returns `null` when
23
+ * no semver parser reads `range`.
24
+ *
25
+ * @remarks Releases on the `unjudged` majors never count as left out. Node publishes no prereleases on a release line,
26
+ * so a prerelease bound such as the `<23.0.0-0` a caret expands to is read as the release it precedes.
27
+ *
28
+ * @since 0.15.0
29
+ */
30
+ export function uncoveredNodeRanges(floor, range, unjudged = []) {
31
+ if (validRange(range) === null) {
32
+ return null;
33
+ }
34
+ const covered = mergeIntervals([
35
+ ...new Range(range).set.flatMap((comparators) => intervalOf(comparators) ?? []),
36
+ ...unjudged.map((major) => ({
37
+ lower: { version: new SemVer(`${major}.0.0`), inclusive: true },
38
+ upper: { version: new SemVer(`${major + 1}.0.0`), inclusive: false },
39
+ })),
40
+ ]);
41
+ const gaps = [];
42
+ let cursor = { version: new SemVer(formatNodeVersion(floor)), inclusive: true };
43
+ for (const interval of covered) {
44
+ if (cursor === null) {
45
+ break;
46
+ }
47
+ if (interval.upper !== null && compareUpperToLower(interval.upper, cursor) < 0) {
48
+ continue;
49
+ }
50
+ if (interval.lower !== null && compareLowers(interval.lower, cursor) > 0) {
51
+ gaps.push(formatInterval({ lower: cursor, upper: flip(interval.lower) }));
52
+ }
53
+ cursor = interval.upper === null ? null : flip(interval.upper);
54
+ }
55
+ if (cursor !== null) {
56
+ gaps.push(formatInterval({ lower: cursor, upper: null }));
57
+ }
58
+ return gaps;
59
+ }
60
+ // The one interval a comparator set admits, or `null` when its bounds cross.
61
+ function intervalOf(comparators) {
62
+ let lower = null;
63
+ let upper = null;
64
+ for (const comparator of comparators) {
65
+ if (comparator.value === "") {
66
+ continue;
67
+ }
68
+ const prerelease = comparator.semver.prerelease.length > 0;
69
+ const version = new SemVer(`${comparator.semver.major}.${comparator.semver.minor}.${comparator.semver.patch}`);
70
+ const { operator } = comparator;
71
+ if (operator === "" || operator === "=" || operator === ">=" || operator === ">") {
72
+ const bound = { version, inclusive: prerelease || operator !== ">" };
73
+ lower = lower === null || compareLowers(bound, lower) > 0 ? bound : lower;
74
+ }
75
+ if (operator === "" || operator === "=" || operator === "<=" || operator === "<") {
76
+ const bound = { version, inclusive: !prerelease && operator !== "<" };
77
+ upper = upper === null || compareUppers(bound, upper) < 0 ? bound : upper;
78
+ }
79
+ }
80
+ if (lower !== null && upper !== null && compareUpperToLower(upper, lower) < 0) {
81
+ return null;
82
+ }
83
+ return { lower, upper };
84
+ }
85
+ // The union of the intervals, sorted and with every overlapping or touching pair joined.
86
+ function mergeIntervals(intervals) {
87
+ const sorted = intervals.toSorted((left, right) => {
88
+ if (left.lower === null || right.lower === null) {
89
+ return left.lower === right.lower ? 0 : left.lower === null ? -1 : 1;
90
+ }
91
+ return compareLowers(left.lower, right.lower);
92
+ });
93
+ const merged = [];
94
+ for (const interval of sorted) {
95
+ const last = merged.at(-1);
96
+ if (last === undefined || (last.upper !== null && compareUpperToLower(last.upper, interval.lower) < 0)) {
97
+ merged.push(interval);
98
+ continue;
99
+ }
100
+ const upper = last.upper === null || interval.upper === null
101
+ ? null
102
+ : compareUppers(interval.upper, last.upper) > 0
103
+ ? interval.upper
104
+ : last.upper;
105
+ merged[merged.length - 1] = { lower: last.lower, upper };
106
+ }
107
+ return merged;
108
+ }
109
+ function compareLowers(left, right) {
110
+ return compare(left.version, right.version) || Number(right.inclusive) - Number(left.inclusive);
111
+ }
112
+ function compareUppers(left, right) {
113
+ return compare(left.version, right.version) || Number(left.inclusive) - Number(right.inclusive);
114
+ }
115
+ // Negative when a version sits strictly between the upper bound and the lower bound, so nothing joins them.
116
+ function compareUpperToLower(upper, lower) {
117
+ if (lower === null) {
118
+ return 1;
119
+ }
120
+ const order = compare(upper.version, lower.version);
121
+ return order !== 0 ? order : upper.inclusive || lower.inclusive ? 0 : -1;
122
+ }
123
+ // The bound that starts where this one ends, on the other side of it.
124
+ function flip(bound) {
125
+ return { version: bound.version, inclusive: !bound.inclusive };
126
+ }
127
+ function formatInterval({ lower, upper }) {
128
+ const parts = [];
129
+ if (lower !== null) {
130
+ parts.push(`${lower.inclusive ? ">=" : ">"}${lower.version.version}`);
131
+ }
132
+ if (upper !== null) {
133
+ parts.push(`${upper.inclusive ? "<=" : "<"}${upper.version.version}`);
134
+ }
135
+ return parts.join(" ");
136
+ }
@@ -0,0 +1,7 @@
1
+ import type { EnginesAuditResult } from "#audit/domain/types";
2
+ /**
3
+ * Human-readable engines audit report.
4
+ *
5
+ * @since 0.15.0
6
+ */
7
+ export declare function presentEnginesAuditResult(result: EnginesAuditResult): void;
@@ -0,0 +1,40 @@
1
+ import { logger } from "#core/logger";
2
+ /**
3
+ * Human-readable engines audit report.
4
+ *
5
+ * @since 0.15.0
6
+ */
7
+ export function presentEnginesAuditResult(result) {
8
+ for (const violation of result.violations) {
9
+ logger.out(`\n${violation.packageName}: ${describeViolation(violation)}`);
10
+ }
11
+ if (result.violations.length > 0) {
12
+ logger.out(`\n✖ ${result.violations.length} Node floor violation(s) across ${result.packageCount} package(s)`);
13
+ return;
14
+ }
15
+ const counts = new Map();
16
+ for (const { floor } of result.floors) {
17
+ counts.set(floor, (counts.get(floor) ?? 0) + 1);
18
+ }
19
+ const summary = [...counts].map(([floor, count]) => `${floor} (${count})`).join(", ") || "none declared";
20
+ logger.out(`✓ Every Node floor holds across ${result.packageCount} package(s): ${summary}`);
21
+ }
22
+ function describeViolation(violation) {
23
+ switch (violation.kind) {
24
+ case "missing-floor": {
25
+ return `declares no engines.node → a published package states the Node floor it supports`;
26
+ }
27
+ case "unparsable-floor": {
28
+ return `engines.node "${violation.range}" → write the floor as ">=X.Y.Z"`;
29
+ }
30
+ case "outside-dependency-engines": {
31
+ return `floor ${violation.floor} claims Node "${violation.uncovered}", which ${violation.dependency}'s engines.node "${violation.range}" (${violation.field}) leaves out → raise the floor or drop the dependency`;
32
+ }
33
+ case "root-outside-dependency-engines": {
34
+ return `workspace root floor ${violation.floor} claims Node "${violation.uncovered}", which ${violation.dependency}'s engines.node "${violation.range}" (installed for ${violation.dependents.join(", ")}) leaves out → raise the root floor or drop the dependency`;
35
+ }
36
+ case "types-off-floor": {
37
+ return `@types/node resolves to ${violation.typesVersion}, off floor ${violation.floor}'s line → pin it to the floor's major at a minor no newer`;
38
+ }
39
+ }
40
+ }
@@ -0,0 +1,16 @@
1
+ import type { AuditCommandPrelude } from "#audit/prepare";
2
+ import type { AppError } from "#core/errors";
3
+ import type { Filesystem } from "#core/filesystem/filesystem";
4
+ import type { Result } from "#core/result";
5
+ /**
6
+ * Loads config and resolves the scan target for `audit engines`.
7
+ *
8
+ * @remarks Defaults to the repo root. A narrower target checks only the packages it reaches, still against the floors
9
+ * of every workspace package they depend on. It takes no allowlist.
10
+ *
11
+ * @since 0.15.0
12
+ */
13
+ export declare function prepareEnginesAudit(fs: Filesystem, args: {
14
+ readonly currentWorkingDirectory: string;
15
+ readonly rawTarget: string | undefined;
16
+ }): Promise<Result<AuditCommandPrelude, AppError>>;
@@ -0,0 +1,12 @@
1
+ import { prepareRepoRootAudit } from "#audit/prepare";
2
+ /**
3
+ * Loads config and resolves the scan target for `audit engines`.
4
+ *
5
+ * @remarks Defaults to the repo root. A narrower target checks only the packages it reaches, still against the floors
6
+ * of every workspace package they depend on. It takes no allowlist.
7
+ *
8
+ * @since 0.15.0
9
+ */
10
+ export async function prepareEnginesAudit(fs, args) {
11
+ return prepareRepoRootAudit(fs, args, () => []);
12
+ }
@@ -0,0 +1,18 @@
1
+ import type { EnginesAuditResult } from "#audit/domain/types";
2
+ import { AppError } from "#core/errors";
3
+ import type { Filesystem } from "#core/filesystem/filesystem";
4
+ import type { Result } from "#core/result";
5
+ /**
6
+ * Reports every Node floor that breaks a rule a consumer or CI depends on.
7
+ *
8
+ * @remarks A published package declares a floor as `>=X.Y.Z`. The `engines.node` of every runtime dependency must
9
+ * admit every release from the floor up, short-lived odd lines aside; that of every dev dependency, the floor and the
10
+ * newest release CI tests on. The `@types/node` the lockfile resolves must declare nothing the floor lacks. The
11
+ * workspace root's floor, never listed among `floors`, must be admitted by every dependency any package installs.
12
+ *
13
+ * @since 0.15.0
14
+ */
15
+ export declare function runEnginesAudit(fs: Filesystem, args: {
16
+ readonly rootDir: string;
17
+ readonly targetPath: string;
18
+ }): Promise<Result<EnginesAuditResult, AppError>>;