@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.
@@ -1,6 +1,6 @@
1
1
  /** @noformat -- @generated. Do not edit. Compiled by rdy. */
2
2
  /* eslint-disable */
3
- export const __readyupVersion = "0.36.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 holds no JavaScript or TypeScript sources outside the exempt paths",
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.
@@ -9,17 +9,17 @@
9
9
  "esbuildVersion": "0.28.2",
10
10
  "inputs": [
11
11
  {
12
- "hash": "1dc83619",
12
+ "hash": "98e2d140",
13
13
  "kind": "module",
14
14
  "path": "../../adoption/src/conventions/path-predicates.ts"
15
15
  },
16
16
  {
17
- "hash": "0237a871",
17
+ "hash": "921ba938",
18
18
  "kind": "module",
19
19
  "path": "../../adoption/src/conventions/site-handoffs.ts"
20
20
  },
21
21
  {
22
- "hash": "8fb83c2d",
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": "0661f0dd",
37
+ "hash": "3867c304",
38
38
  "kind": "module",
39
39
  "path": "../../adoption/src/portable/listDirectoryAscents.ts"
40
40
  },
41
41
  {
42
- "hash": "07c8358f",
42
+ "hash": "982f3e6d",
43
43
  "kind": "module",
44
44
  "path": "../../adoption/src/portable/listFunctionBodies.ts"
45
45
  },
46
46
  {
47
- "hash": "2d9f1edb",
47
+ "hash": "ce2e063d",
48
48
  "kind": "module",
49
49
  "path": "../../adoption/src/portable/listTemplateLiterals.ts"
50
50
  },
51
51
  {
52
- "hash": "b0751395",
52
+ "hash": "a5dc0993",
53
53
  "kind": "module",
54
54
  "path": "../../adoption/src/portable/readAnchoredWindow.ts"
55
55
  },
56
56
  {
57
- "hash": "0eb1daf1",
57
+ "hash": "9ff7cd2c",
58
58
  "kind": "module",
59
59
  "path": "../../adoption/src/portable/readBalancedGroup.ts"
60
60
  },
61
61
  {
62
- "hash": "e9427d50",
62
+ "hash": "81846f1a",
63
63
  "kind": "module",
64
64
  "path": "../../adoption/src/portable/readLiteral.ts"
65
65
  },
66
66
  {
67
- "hash": "716f73e7",
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": "33959e51",
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.36.0",
84
+ "readyupVersion": "0.38.0",
85
85
  "source": "kits/default.ts",
86
- "sourceHash": "716f73e7",
87
- "targetHash": "40c1567e"
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 reaches 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.
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 holding a `package.json`, reported as `source: 'package-json'`;
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", where [`findPackageRoot`](#findpackageroot) answers "which package declares me". A monorepo has one project root and many package roots.
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 shipped alongside that package resolve from.
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 sit at different depths and no fixed number of `..` hops suits both.
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
- A module belonging to no named package throws, 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. A manifest that is unreadable as JSON, or that parses to something other than an object, throws by name rather than being skipped: Corruption is a defect, not an absence.
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 would read its version as `undefined` rather than raising, since the marker manifest declares none.
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
- A manifest that declares a `name` but no string `version` throws, naming the manifest. The ascent does not continue past it, so a versionless package never reports an ancestor's version as its own.
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 ships a ReadyUp kit, so a project that installs it can ask how far its adoption got:
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) where the loop goes on to read the manifest's version; both pass over a manifest that declares no name. The project that holds a directory takes [`findProjectRoot`](#findprojectroot), which prefers `.git` and lockfiles to a manifest and so returns the repository root in a monorepo. The nearest manifest, whatever it declares, takes `findDirectoryChainMatch` from `@williamthorsen/toolbelt.filesystem`.
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, '..')` carries 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 holding 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.
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. The sweep is readyup's, so this holds on readyup 0.35.0 or later.
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, where the two sit at different depths.
8
+ * source tree and a compiled one, even though the two are at different depths.
9
9
  *
10
- * A module belonging to no package is an error rather than a fallback, so the return is a bare directory.
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 sit at different depths. A manifest declaring a `name` but no string `version` raises rather than
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 holding a `package.json`, then to `startDir` itself; both fallbacks report a `null` marker.
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 holds.
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.0",
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.0"
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.0",
52
+ "@williamthorsen/toolbelt.testing": "0.6.2",
53
53
  "esbuild": "0.28.2",
54
- "readyup": "0.36.0"
54
+ "readyup": "0.38.0"
55
55
  },
56
56
  "engines": {
57
57
  "node": ">=24.0.0"