@williamthorsen/toolbelt.packaging 0.6.0 → 0.6.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.readyup/kits/default.js +2 -2
- package/.readyup/manifest.json +14 -14
- package/CHANGELOG.md +7 -0
- package/README.md +14 -38
- package/dist/esm/3-candidate/findPackageRoot.d.ts +2 -2
- package/dist/esm/3-candidate/resolveSelfVersion.d.ts +1 -1
- package/dist/esm/4-release/findProjectRoot.d.ts +1 -1
- package/dist/esm/internal/resolveOwningManifest.d.ts +1 -1
- package/package.json +4 -4
package/.readyup/kits/default.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/** @noformat -- @generated. Do not edit. Compiled by rdy. */
|
|
2
2
|
/* eslint-disable */
|
|
3
|
-
export const __readyupVersion = "0.
|
|
3
|
+
export const __readyupVersion = "0.38.0";
|
|
4
4
|
|
|
5
5
|
|
|
6
6
|
// ../adoption/src/conventions/path-predicates.ts
|
|
@@ -389,7 +389,7 @@ var default_default = defineAdoptionKit({
|
|
|
389
389
|
description: `Adoption checks for a project consuming ${PACKAGE_NAME}`,
|
|
390
390
|
detect: listManifestSearchSites,
|
|
391
391
|
exportNames: ADOPTED_EXPORTS,
|
|
392
|
-
noSourcesReason: "the project
|
|
392
|
+
noSourcesReason: "the project contains no JavaScript or TypeScript sources outside the exempt paths",
|
|
393
393
|
packageName: PACKAGE_NAME,
|
|
394
394
|
// A test writes this walk deliberately, and a bootstrap wrapper hand-rolls what it reaches for so that its
|
|
395
395
|
// build-first message survives an incomplete install.
|
package/.readyup/manifest.json
CHANGED
|
@@ -9,17 +9,17 @@
|
|
|
9
9
|
"esbuildVersion": "0.28.2",
|
|
10
10
|
"inputs": [
|
|
11
11
|
{
|
|
12
|
-
"hash": "
|
|
12
|
+
"hash": "98e2d140",
|
|
13
13
|
"kind": "module",
|
|
14
14
|
"path": "../../adoption/src/conventions/path-predicates.ts"
|
|
15
15
|
},
|
|
16
16
|
{
|
|
17
|
-
"hash": "
|
|
17
|
+
"hash": "921ba938",
|
|
18
18
|
"kind": "module",
|
|
19
19
|
"path": "../../adoption/src/conventions/site-handoffs.ts"
|
|
20
20
|
},
|
|
21
21
|
{
|
|
22
|
-
"hash": "
|
|
22
|
+
"hash": "e6e87602",
|
|
23
23
|
"kind": "module",
|
|
24
24
|
"path": "../../adoption/src/kits/defineAdoptionKit.ts"
|
|
25
25
|
},
|
|
@@ -34,37 +34,37 @@
|
|
|
34
34
|
"path": "../../adoption/src/portable/condenseWhitespace.ts"
|
|
35
35
|
},
|
|
36
36
|
{
|
|
37
|
-
"hash": "
|
|
37
|
+
"hash": "3867c304",
|
|
38
38
|
"kind": "module",
|
|
39
39
|
"path": "../../adoption/src/portable/listDirectoryAscents.ts"
|
|
40
40
|
},
|
|
41
41
|
{
|
|
42
|
-
"hash": "
|
|
42
|
+
"hash": "982f3e6d",
|
|
43
43
|
"kind": "module",
|
|
44
44
|
"path": "../../adoption/src/portable/listFunctionBodies.ts"
|
|
45
45
|
},
|
|
46
46
|
{
|
|
47
|
-
"hash": "
|
|
47
|
+
"hash": "ce2e063d",
|
|
48
48
|
"kind": "module",
|
|
49
49
|
"path": "../../adoption/src/portable/listTemplateLiterals.ts"
|
|
50
50
|
},
|
|
51
51
|
{
|
|
52
|
-
"hash": "
|
|
52
|
+
"hash": "a5dc0993",
|
|
53
53
|
"kind": "module",
|
|
54
54
|
"path": "../../adoption/src/portable/readAnchoredWindow.ts"
|
|
55
55
|
},
|
|
56
56
|
{
|
|
57
|
-
"hash": "
|
|
57
|
+
"hash": "9ff7cd2c",
|
|
58
58
|
"kind": "module",
|
|
59
59
|
"path": "../../adoption/src/portable/readBalancedGroup.ts"
|
|
60
60
|
},
|
|
61
61
|
{
|
|
62
|
-
"hash": "
|
|
62
|
+
"hash": "81846f1a",
|
|
63
63
|
"kind": "module",
|
|
64
64
|
"path": "../../adoption/src/portable/readLiteral.ts"
|
|
65
65
|
},
|
|
66
66
|
{
|
|
67
|
-
"hash": "
|
|
67
|
+
"hash": "9b6938d1",
|
|
68
68
|
"kind": "module",
|
|
69
69
|
"path": "kits/default.ts"
|
|
70
70
|
},
|
|
@@ -74,17 +74,17 @@
|
|
|
74
74
|
"path": "../src/readiness/adoptedExports.ts"
|
|
75
75
|
},
|
|
76
76
|
{
|
|
77
|
-
"hash": "
|
|
77
|
+
"hash": "f78c7a58",
|
|
78
78
|
"kind": "module",
|
|
79
79
|
"path": "../src/readiness/listManifestSearchSites.ts"
|
|
80
80
|
}
|
|
81
81
|
],
|
|
82
82
|
"name": "default",
|
|
83
83
|
"path": "kits/default.js",
|
|
84
|
-
"readyupVersion": "0.
|
|
84
|
+
"readyupVersion": "0.38.0",
|
|
85
85
|
"source": "kits/default.ts",
|
|
86
|
-
"sourceHash": "
|
|
87
|
-
"targetHash": "
|
|
86
|
+
"sourceHash": "9b6938d1",
|
|
87
|
+
"targetHash": "bc16d87b"
|
|
88
88
|
}
|
|
89
89
|
]
|
|
90
90
|
}
|
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## 0.6.2 — 2026-10-02
|
|
6
|
+
|
|
7
|
+
### 📚 Documentation
|
|
8
|
+
|
|
9
|
+
- Revises READMEs, doc comments, and test names across the repository to follow the current `plain-speech` and writing-preference rules. (#354)
|
|
10
|
+
- Rewords the help text and messages printed by `tb-jira`, `tb-node`, and `tb-secret`, and the advice and skip reasons reported by the adoption kits, to follow the same writing conventions. (#354)
|
|
11
|
+
|
|
5
12
|
## 0.6.0 — 2026-09-15
|
|
6
13
|
|
|
7
14
|
### 🎉 Features
|
package/README.md
CHANGED
|
@@ -4,31 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
Package and project layout utilities for TypeScript and JavaScript: where a package or project boundary begins, and what the manifest at that boundary declares.
|
|
6
6
|
|
|
7
|
-
<!-- section:release-notes -->
|
|
8
|
-
## Release notes — v0.6.0 (2026-09-15)
|
|
9
|
-
|
|
10
|
-
### 🎉 Features
|
|
11
|
-
|
|
12
|
-
- 🚨 **Breaking:** Move createTempTree from toolbelt.filesystem to toolbelt.testing (#313)
|
|
13
|
-
|
|
14
|
-
- Moves `CreateTempTreeOptions` and the `TempTree` handle to `@williamthorsen/toolbelt.testing/candidate` along with `createTempTree`.
|
|
15
|
-
|
|
16
|
-
Migration: Import `createTempTree`, `CreateTempTreeOptions`, and `TempTree` from `@williamthorsen/toolbelt.testing/candidate`, and declare `@williamthorsen/toolbelt.testing` in the manifest that declared `@williamthorsen/toolbelt.filesystem` for them.
|
|
17
|
-
|
|
18
|
-
- Add a ReadyUp adoption kit reporting hand-rolled package.json searches (#322)
|
|
19
|
-
|
|
20
|
-
- Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.packaging` that recommends `findPackageRoot`, `resolveSelfVersion`, or `findProjectRoot` in place of a hand-rolled loop checking each ancestor directory for `package.json`.
|
|
21
|
-
|
|
22
|
-
- Read a directory walk's probed name through a binding or constant (#324)
|
|
23
|
-
|
|
24
|
-
- Extends the ReadyUp adoption kit in `@williamthorsen/toolbelt.packaging` to recommend `findPackageRoot` or `resolveSelfVersion` for a hand-rolled `package.json` search that checks for the file through a variable declared once inside its loop and never reassigned there, or through a string constant declared once in the same file.
|
|
25
|
-
- Stops the kit in `@williamthorsen/toolbelt.filesystem` from reporting such a search, which it previously treated as a generic directory walk.
|
|
26
|
-
|
|
27
|
-
- Report hand-rolled dedents in the strings adoption kit (#330)
|
|
28
|
-
|
|
29
|
-
- Adds `no-joined-line-array`, which reports an array of string or template literals that spans several lines and is joined with a newline.
|
|
30
|
-
- Adds `no-layout-breaking-template`, which reports an untagged template literal whose later lines drop below the indentation of the line on which it opens.
|
|
31
|
-
<!-- /section:release-notes -->
|
|
7
|
+
<!-- section:release-notes --><!-- /section:release-notes -->
|
|
32
8
|
|
|
33
9
|
## Installation
|
|
34
10
|
|
|
@@ -38,7 +14,7 @@ pnpm add @williamthorsen/toolbelt.packaging
|
|
|
38
14
|
|
|
39
15
|
## Runtime requirements
|
|
40
16
|
|
|
41
|
-
Every export
|
|
17
|
+
Every export accesses the filesystem through `node:` builtins, so they run under Node.js 24 or later, Bun, and Deno. They do not run in browsers, nor in edge runtimes that expose no filesystem.
|
|
42
18
|
|
|
43
19
|
## `findProjectRoot`
|
|
44
20
|
|
|
@@ -77,12 +53,12 @@ Each marker is a path relative to the level against which it is probed, on the t
|
|
|
77
53
|
|
|
78
54
|
When no directory up to and including the filesystem root contains a marker, the result falls back in this order, reporting a `null` marker either way:
|
|
79
55
|
|
|
80
|
-
1. the nearest ancestor
|
|
56
|
+
1. the nearest ancestor containing a `package.json`, reported as `source: 'package-json'`;
|
|
81
57
|
2. `startDir` itself, reported as `source: 'start-dir'`.
|
|
82
58
|
|
|
83
59
|
The ascent terminates at the filesystem root on every platform, so a Windows drive root or UNC share is as safe a starting point as a POSIX path.
|
|
84
60
|
|
|
85
|
-
A project root is not a package root: This answers "which checkout am I in",
|
|
61
|
+
A project root is not a package root: This answers "which checkout am I in", whereas [`findPackageRoot`](#findpackageroot) answers "which package declares me". A monorepo has one project root and many package roots.
|
|
86
62
|
|
|
87
63
|
## `findPackageRoot`
|
|
88
64
|
|
|
@@ -92,7 +68,7 @@ Candidate tier: Imported from `@williamthorsen/toolbelt.packaging/candidate` rat
|
|
|
92
68
|
findPackageRoot(fromUrl: string): string;
|
|
93
69
|
```
|
|
94
70
|
|
|
95
|
-
Returns the directory of the package that owns a module, which is where assets
|
|
71
|
+
Returns the directory of the package that owns a module, which is where assets published with that package resolve from.
|
|
96
72
|
|
|
97
73
|
```ts
|
|
98
74
|
import path from 'node:path';
|
|
@@ -102,7 +78,7 @@ import { findPackageRoot } from '@williamthorsen/toolbelt.packaging/candidate';
|
|
|
102
78
|
const templatesDir = path.join(findPackageRoot(import.meta.url), 'templates');
|
|
103
79
|
```
|
|
104
80
|
|
|
105
|
-
Pass `import.meta.url`. A module's own URL is the only input that resolves correctly from both a source tree and a compiled one, because the two
|
|
81
|
+
Pass `import.meta.url`. A module's own URL is the only input that resolves correctly from both a source tree and a compiled one, because the two are at different depths and no fixed number of `..` hops suits both.
|
|
106
82
|
|
|
107
83
|
The owning package is the nearest ancestor whose `package.json` declares a `name`. That rule distinguishes this from `findPackageJSON` in `node:module`, which answers the different question of which manifest _governs_ a file:
|
|
108
84
|
|
|
@@ -111,9 +87,9 @@ The owning package is the nearest ancestor whose `package.json` declares a `name
|
|
|
111
87
|
{ "type": "commonjs" }
|
|
112
88
|
```
|
|
113
89
|
|
|
114
|
-
A dual-format build leaves that file so the runtime parses `dist/cjs/` as CommonJS. `findPackageJSON` stops there and reports it; `findPackageRoot` passes over it and keeps ascending to the manifest that declares the package's identity.
|
|
90
|
+
A dual-format build leaves that file so that the runtime parses `dist/cjs/` as CommonJS. `findPackageJSON` stops there and reports it; `findPackageRoot` passes over it and keeps ascending to the manifest that declares the package's identity.
|
|
115
91
|
|
|
116
|
-
|
|
92
|
+
The function throws for a module belonging to no named package, rather than falling back to a directory that merely looks plausible, which is why the return is a bare string with no evidence to interpret. It throws on a manifest that is unreadable as JSON, or that parses to something other than an object, naming the manifest rather than skipping it: Corruption is a defect, not an absence.
|
|
117
93
|
|
|
118
94
|
## `resolveSelfVersion`
|
|
119
95
|
|
|
@@ -131,13 +107,13 @@ import { resolveSelfVersion } from '@williamthorsen/toolbelt.packaging/candidate
|
|
|
131
107
|
console.log(`my-cli ${resolveSelfVersion(import.meta.url)}`);
|
|
132
108
|
```
|
|
133
109
|
|
|
134
|
-
Ownership is resolved exactly as [`findPackageRoot`](#findpackageroot) resolves it, so a marker manifest is passed over here too. Without that, a dual-format build
|
|
110
|
+
Ownership is resolved exactly as [`findPackageRoot`](#findpackageroot) resolves it, so a marker manifest is passed over here too. Without that, the function would read a dual-format build's version as `undefined` rather than raising, since the marker manifest declares none.
|
|
135
111
|
|
|
136
|
-
|
|
112
|
+
The function throws on a manifest that declares a `name` but no string `version`, naming the manifest. Because the ascent does not continue past it, the function never reports an ancestor's version as a versionless package's own.
|
|
137
113
|
|
|
138
114
|
## Adoption checks
|
|
139
115
|
|
|
140
|
-
The package
|
|
116
|
+
The package includes a ReadyUp kit, so a project that installs it can ask how far its adoption got:
|
|
141
117
|
|
|
142
118
|
```sh
|
|
143
119
|
rdy run --packages
|
|
@@ -145,13 +121,13 @@ rdy run --packages
|
|
|
145
121
|
|
|
146
122
|
The kit reads the project's tracked sources and reports one idiom, counted against the calls that the project already makes into this package. It reports at `recommend`: A hand-rolled search is correct code that a published function expresses better, not a defect.
|
|
147
123
|
|
|
148
|
-
`no-hand-rolled-manifest-search` reports a loop that ascends by `dirname` and probes each level for `package.json`, naming the line on which the loop opens. The scan reads which names a loop probes, but not where the loop starts or what it does with the manifest, so the fix text sets out the choice by purpose. The package that owns the running module takes [`findPackageRoot`](#findpackageroot), or [`resolveSelfVersion`](#resolveselfversion)
|
|
124
|
+
`no-hand-rolled-manifest-search` reports a loop that ascends by `dirname` and probes each level for `package.json`, naming the line on which the loop opens. The scan reads which names a loop probes, but not where the loop starts or what it does with the manifest, so the fix text sets out the choice by purpose. The package that owns the running module takes [`findPackageRoot`](#findpackageroot), or [`resolveSelfVersion`](#resolveselfversion) when the loop goes on to read the manifest's version; both pass over a manifest that declares no name. The project that contains a directory takes [`findProjectRoot`](#findprojectroot), which prefers `.git` and lockfiles to a manifest, returning the repository root in a monorepo. The nearest manifest, whatever it declares, takes `findDirectoryChainMatch` from `@williamthorsen/toolbelt.filesystem`.
|
|
149
125
|
|
|
150
126
|
Every other walk up the directory chain belongs to [`@williamthorsen/toolbelt.filesystem`](https://github.com/williamthorsen/toolbelt/tree/main/packages/filesystem#adoption-checks), whose own kit reports it: a loop probing for root markers alone, such as `.git`; a loop probing for a manifest below the level, such as `node_modules/x/package.json`; and a loop that probes nothing. Reporting one here as well would show one loop twice under conflicting advice. A read of `package.json` outside any loop, and a loop over the directories listed by `listDirectoryChain`, ascend nothing by hand, and neither kit reports them.
|
|
151
127
|
|
|
152
|
-
The detector under-matches by design. A recursive walk-up function is no loop, an ascent written as `path.resolve(dir, '..')`
|
|
128
|
+
The detector under-matches by design. A recursive walk-up function is no loop, an ascent written as `path.resolve(dir, '..')` has a different anchor, and a loop whose body is a single unbraced statement goes unread, and neither kit reports any of the three. A probe for `package.json` made through a helper, through a constant imported from another module, or through a binding declared outside the loop names no manifest that the scan can read, and neither does a path containing another binding past the level, as `${dir}/${name}/package.json` does. `toolbelt.filesystem` reports each loop probing in one of these ways as a walk instead.
|
|
153
129
|
|
|
154
|
-
Bootstrap wrappers under `bin/` are exempt: Such a wrapper imports only builtins so its build-first message survives an incomplete install, and importing this package there would replace that message with a module-resolution failure. Tests are exempt too, since they write this walk deliberately. A source declared generated or vendored by the project in its own `.gitattributes`, under `linguist-generated` or `linguist-vendored`, is exempt as well: The sweep drops it before the kit sees it, so committed bundler output yields no advice that anyone could act on.
|
|
130
|
+
Bootstrap wrappers under `bin/` are exempt: Such a wrapper imports only builtins so that its build-first message survives an incomplete install, and importing this package there would replace that message with a module-resolution failure. Tests are exempt too, since they write this walk deliberately. A source declared generated or vendored by the project in its own `.gitattributes`, under `linguist-generated` or `linguist-vendored`, is exempt as well: The sweep drops it before the kit sees it, so committed bundler output yields no advice that anyone could act on. Because the sweep is readyup's, this holds on readyup 0.35.0 or later.
|
|
155
131
|
|
|
156
132
|
A reviewed site is silenced by an `rdy-ignore` pragma on its own line, or `rdy-ignore-next-line` on the line above. A pragma naming a check's id suppresses that check alone; with no id it covers every check on the line. A failed check prints its id ahead of its fraction, which is the form to write:
|
|
157
133
|
|
|
@@ -5,9 +5,9 @@
|
|
|
5
5
|
* The owning package is the nearest ancestor whose `package.json` declares a `name`, so a marker manifest --
|
|
6
6
|
* the `{"type": "commonjs"}` file left in `dist/` by a dual-format build -- is passed over rather than
|
|
7
7
|
* returned. Pass `import.meta.url`: A module's own URL is the only input that resolves correctly from both a
|
|
8
|
-
* source tree and a compiled one,
|
|
8
|
+
* source tree and a compiled one, even though the two are at different depths.
|
|
9
9
|
*
|
|
10
|
-
*
|
|
10
|
+
* Because a module belonging to no package is an error rather than a fallback, the return is a bare directory.
|
|
11
11
|
*
|
|
12
12
|
* @example
|
|
13
13
|
* findPackageRoot(import.meta.url); // '/home/dev/my-app/node_modules/some-package'
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* Returns the version declared by the package that owns the module at `fromUrl`.
|
|
3
3
|
*
|
|
4
4
|
* Pass `import.meta.url`, which reports the same version from a source tree and a compiled one even though
|
|
5
|
-
* the two
|
|
5
|
+
* the two are at different depths. A manifest declaring a `name` but no string `version` raises rather than
|
|
6
6
|
* letting the ascent continue, so a versionless package never reports an ancestor's version as its own.
|
|
7
7
|
*
|
|
8
8
|
* @example
|
|
@@ -13,7 +13,7 @@ export declare const DEFAULT_ROOT_MARKERS: ReadonlyArray<string>;
|
|
|
13
13
|
*
|
|
14
14
|
* Ascends from `startDir` (resolved to an absolute path) and returns the first directory that contains one of
|
|
15
15
|
* `markers`. If no directory up to and including the filesystem root contains one, falls back to the nearest
|
|
16
|
-
* ancestor
|
|
16
|
+
* ancestor containing a `package.json`, then to `startDir` itself; both fallbacks report a `null` marker.
|
|
17
17
|
*
|
|
18
18
|
* @example
|
|
19
19
|
* findProjectRoot(import.meta.dirname); // { marker: '.git', rootDir: '/home/dev/my-app', source: 'marker' }
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
* Ascends from the module's own directory and returns the first `package.json` declaring a `name`. One that
|
|
5
5
|
* declares none is a marker manifest, such as the `{"type": "commonjs"}` file left in `dist/` by a dual-format
|
|
6
6
|
* build, and the ascent passes over it. That is the whole difference from `node:module`'s `findPackageJSON`,
|
|
7
|
-
* which returns the nearest manifest whatever it
|
|
7
|
+
* which returns the nearest manifest whatever it contains.
|
|
8
8
|
*
|
|
9
9
|
* @internal
|
|
10
10
|
*/
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@williamthorsen/toolbelt.packaging",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.2",
|
|
4
4
|
"description": "Package and project layout utilities: where a package or project boundary begins, and what its manifest declares",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"esm",
|
|
@@ -45,13 +45,13 @@
|
|
|
45
45
|
"CHANGELOG.md"
|
|
46
46
|
],
|
|
47
47
|
"dependencies": {
|
|
48
|
-
"@williamthorsen/toolbelt.filesystem": "0.9.
|
|
48
|
+
"@williamthorsen/toolbelt.filesystem": "0.9.2"
|
|
49
49
|
},
|
|
50
50
|
"devDependencies": {
|
|
51
51
|
"@williamthorsen/toolbelt.adoption": "0.1.0",
|
|
52
|
-
"@williamthorsen/toolbelt.testing": "0.6.
|
|
52
|
+
"@williamthorsen/toolbelt.testing": "0.6.2",
|
|
53
53
|
"esbuild": "0.28.2",
|
|
54
|
-
"readyup": "0.
|
|
54
|
+
"readyup": "0.38.0"
|
|
55
55
|
},
|
|
56
56
|
"engines": {
|
|
57
57
|
"node": ">=24.0.0"
|