@williamthorsen/toolbelt.packaging 0.6.1 → 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.37.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.37.0",
84
+ "readyupVersion": "0.38.0",
85
85
  "source": "kits/default.ts",
86
- "sourceHash": "716f73e7",
87
- "targetHash": "df62f14b"
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
@@ -14,7 +14,7 @@ pnpm add @williamthorsen/toolbelt.packaging
14
14
 
15
15
  ## Runtime requirements
16
16
 
17
- 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.
18
18
 
19
19
  ## `findProjectRoot`
20
20
 
@@ -53,12 +53,12 @@ Each marker is a path relative to the level against which it is probed, on the t
53
53
 
54
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:
55
55
 
56
- 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'`;
57
57
  2. `startDir` itself, reported as `source: 'start-dir'`.
58
58
 
59
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.
60
60
 
61
- 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.
62
62
 
63
63
  ## `findPackageRoot`
64
64
 
@@ -68,7 +68,7 @@ Candidate tier: Imported from `@williamthorsen/toolbelt.packaging/candidate` rat
68
68
  findPackageRoot(fromUrl: string): string;
69
69
  ```
70
70
 
71
- 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.
72
72
 
73
73
  ```ts
74
74
  import path from 'node:path';
@@ -78,7 +78,7 @@ import { findPackageRoot } from '@williamthorsen/toolbelt.packaging/candidate';
78
78
  const templatesDir = path.join(findPackageRoot(import.meta.url), 'templates');
79
79
  ```
80
80
 
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 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.
82
82
 
83
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:
84
84
 
@@ -87,9 +87,9 @@ The owning package is the nearest ancestor whose `package.json` declares a `name
87
87
  { "type": "commonjs" }
88
88
  ```
89
89
 
90
- 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.
91
91
 
92
- 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.
93
93
 
94
94
  ## `resolveSelfVersion`
95
95
 
@@ -107,13 +107,13 @@ import { resolveSelfVersion } from '@williamthorsen/toolbelt.packaging/candidate
107
107
  console.log(`my-cli ${resolveSelfVersion(import.meta.url)}`);
108
108
  ```
109
109
 
110
- 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.
111
111
 
112
- 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.
113
113
 
114
114
  ## Adoption checks
115
115
 
116
- 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:
117
117
 
118
118
  ```sh
119
119
  rdy run --packages
@@ -121,13 +121,13 @@ rdy run --packages
121
121
 
122
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.
123
123
 
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) 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`.
125
125
 
126
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.
127
127
 
128
- 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.
129
129
 
130
- 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.
131
131
 
132
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:
133
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.1",
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.1"
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.1",
52
+ "@williamthorsen/toolbelt.testing": "0.6.2",
53
53
  "esbuild": "0.28.2",
54
- "readyup": "0.37.0"
54
+ "readyup": "0.38.0"
55
55
  },
56
56
  "engines": {
57
57
  "node": ">=24.0.0"