@williamthorsen/toolbelt.git 0.4.0 → 0.4.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/CHANGELOG.md CHANGED
@@ -2,6 +2,19 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## 0.4.2 — 2026-10-02
6
+
7
+ ### 📚 Documentation
8
+
9
+ - Audits the comments in every authored TypeScript, JavaScript, shell, and YAML source and every `tsconfig*.json` against the comment discipline, cutting comments that paraphrase the code or narrate history, rewriting doc descriptions in the third-person indicative, and adding descriptions to the functions, methods, and classes that had none. (#353)
10
+ - Revises READMEs, doc comments, and test names across the repository to follow the current `plain-speech` and writing-preference rules. (#354)
11
+
12
+ ## 0.4.1 — 2026-09-17
13
+
14
+ ### Dependency updates
15
+
16
+ - Bumped `@williamthorsen/toolbelt.strings` to 8.0.1
17
+
5
18
  ## 0.4.0 — 2026-09-15
6
19
 
7
20
  ### 🎉 Features
package/README.md CHANGED
@@ -2,17 +2,7 @@
2
2
 
3
3
  Utilities for working with git.
4
4
 
5
- <!-- section:release-notes -->
6
- ## Release notes — v0.4.0 (2026-09-15)
7
-
8
- ### 🎉 Features
9
-
10
- - 🚨 **Breaking:** Move createTempTree from toolbelt.filesystem to toolbelt.testing (#313)
11
-
12
- - Moves `CreateTempTreeOptions` and the `TempTree` handle to `@williamthorsen/toolbelt.testing/candidate` along with `createTempTree`.
13
-
14
- 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.
15
- <!-- /section:release-notes -->
5
+ <!-- section:release-notes --><!-- /section:release-notes -->
16
6
 
17
7
  ## Installation
18
8
 
@@ -24,7 +14,7 @@ Requires Node.js 24 or later.
24
14
 
25
15
  ## CLI
26
16
 
27
- The package ships a `tb-git` command exposing the same functions to a shell caller.
17
+ The package provides a `tb-git` command exposing the same functions to a shell caller.
28
18
 
29
19
  ```sh
30
20
  pnpm add --global @williamthorsen/toolbelt.git # puts tb-git on PATH
@@ -51,7 +41,7 @@ tb-git branch-number 232_add-widget --min 3000 --max 3999
51
41
  # 3232
52
42
  ```
53
43
 
54
- A negative offset takes the `=` form, `--offset=-3`: A bare `-3` reads as an option rather than as the value.
44
+ A negative offset takes the `=` form, `--offset=-3`: A bare `-3` is parsed as an option rather than as the value.
55
45
 
56
46
  ### `tb-git ticket-ref [<branch>] [options]`
57
47
 
@@ -82,7 +72,7 @@ With no `<branch>`, both subcommands resolve the checked-out branch with `git br
82
72
  | `1` | `ticket-ref` found no ticket in the branch name; both streams are empty |
83
73
  | `2` | Usage or validation error, with the message on stderr |
84
74
 
85
- A bound, offset, or key rejected by the library exits `2`, reporting the message that it raises. So does an empty option value, so `--min "$PORT_MIN"` with `PORT_MIN` unset fails instead of bounding at `0`.
75
+ `tb-git` exits `2` when the library rejects a bound, offset, or key, and reports the message that the library raises. It also exits `2` on an empty option value: `--min "$PORT_MIN"` with `PORT_MIN` unset fails instead of bounding at `0`.
86
76
 
87
77
  ```sh
88
78
  if ref=$(tb-git ticket-ref); then
@@ -115,11 +105,11 @@ findBranchTicketRef('232_add-widget');
115
105
  // { id: '232', number: 232 }
116
106
  ```
117
107
 
118
- A ref must begin a segment. `/` and `_` both delimit one, so an author prefix and a worktree-safe spelling parse alike, and the leftmost segment with a ref wins. Anchoring to a segment keeps a kebab-case description from reading as a ticket: `feat/add-widget-2` encodes none, because `widget` follows a hyphen rather than a separator.
108
+ A ref must begin a segment. `/` and `_` both delimit one, so an author prefix and a worktree-safe spelling parse alike, and the leftmost segment with a ref is taken. Anchoring to a segment keeps a kebab-case description from being parsed as a ticket: `feat/add-widget-2` encodes none, because `widget` follows a hyphen rather than a separator.
119
109
 
120
110
  Two forms are recognized, each taking an optional `.N` revisit suffix. A **keyed** ref is a Jira-style key and number, the key matching Jira's own rule of a letter followed by letters and digits. A **bare-numeric** ref is the number alone. `id` and `key` are emitted uppercased, since a branch name may be lowercase but the ticket that it names is `MAC-22`.
121
111
 
122
- By default a key must be uppercase, which Jira permits and which is the only property separating a real key from an ordinary word: Without it, `feat-2` would read as ticket `FEAT-2`. Declaring the project's own key through `key` is both more permissive and more precise, since it then matches in any casing and is the only key that matches at all.
112
+ By default a key must be uppercase, which Jira permits and which is the only property separating a real key from an ordinary word: Without it, `feat-2` would be parsed as ticket `FEAT-2`. Declaring the project's own key through `key` is both more permissive and more precise, since it then matches in any casing and is the only key that matches at all.
123
113
 
124
114
  ```ts
125
115
  findBranchTicketRef('mac-22/add-widget');
@@ -154,7 +144,7 @@ deriveBranchNumber('main');
154
144
  // 663286764
155
145
  ```
156
146
 
157
- The number is the ticket's when the branch names one, and a [`hashString`](https://github.com/williamthorsen/toolbelt/tree/main/packages/strings#hashstring) digest of the whole name when it does not, so every branch yields something. `min`, `max`, and `offset` are `hashString`'s, and apply to both paths alike: The two land in one range, and `offset` stays a pure rotation.
147
+ The number is the ticket's when the branch names one, and a [`hashString`](https://github.com/williamthorsen/toolbelt/tree/main/packages/strings#hashstring) digest of the whole name when it does not, so every branch yields something. `min`, `max`, and `offset` are `hashString`'s, and apply to both paths alike: The two produce a number in one range, and `offset` stays a pure rotation.
158
148
 
159
149
  ```ts
160
150
  deriveBranchNumber('232_add-widget', { min: 3000, max: 3999 });
@@ -164,4 +154,4 @@ deriveBranchNumber('refactor/tidy-imports', { min: 3000, max: 3999 });
164
154
  // 3508
165
155
  ```
166
156
 
167
- A number that overruns the range wraps into it, so `deriveBranchNumber('1232', { max: 999 })` is `232`. `key` is passed through to `findBranchTicketRef`, and a bad `key`, bound, or offset raises the same `RangeError` whether or not the branch names a ticket.
157
+ A number that overruns the range wraps into it: `deriveBranchNumber('1232', { max: 999 })` is `232`. `key` is passed through to `findBranchTicketRef`, and a bad `key`, bound, or offset raises the same `RangeError` whether or not the branch names a ticket.
package/bin/tb-git.js CHANGED
@@ -4,12 +4,12 @@
4
4
  // dependency would replace this file's build-first message with ERR_MODULE_NOT_FOUND.
5
5
  import { existsSync } from 'node:fs';
6
6
 
7
- // Thin wrapper so pnpm can link the bin at install time, before `dist/` exists. The real entry point loads
7
+ // Thin wrapper so that pnpm can link the bin at install time, before `dist/` exists. The real entry point loads
8
8
  // at runtime from the build output.
9
9
  const entryPoint = new URL('../dist/esm/bin/tb-git.js', import.meta.url);
10
10
 
11
- // Gate on the entry file itself: Node raises ERR_MODULE_NOT_FOUND for any unresolved module in the graph,
12
- // so keying the build-first message off the error code would also fire when the build is present and one
11
+ // Gate on the entry file itself: Because Node raises ERR_MODULE_NOT_FOUND for any unresolved module in the
12
+ // graph, keying the build-first message off the error code would also fire when the build is present and one
13
13
  // of its imports is missing.
14
14
  if (!existsSync(entryPoint)) {
15
15
  process.stderr.write(
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * Finds the ticket ref encoded by a branch name, or `undefined` when it encodes none. A ref must begin a
3
- * `/`- or `_`-delimited segment, and the leftmost segment containing one wins. A key must be uppercase,
3
+ * `/`- or `_`-delimited segment, and the leftmost segment containing one is taken. A key must be uppercase,
4
4
  * unless `key` names the project's own key, which then matches in any casing and is the only key that
5
5
  * does; a bare-numeric ref is found either way. Throws a RangeError if `key` is not a well-formed key.
6
6
  *
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * Finds the manifest of the package owning a directory, ascending to the first `package.json` declaring a
3
3
  * `name`. One declaring none is a marker manifest, such as the `{"type": "commonjs"}` file left in `dist/`
4
- * by a dual-format build, and the ascent passes over it, so the answer is the owning package rather than
5
- * the nearest manifest. Throws where no ancestor declares a name.
4
+ * by a dual-format build, and the ascent passes over it, so the function returns the owning package's
5
+ * manifest rather than the nearest one. Throws when no ancestor declares a name.
6
6
  *
7
7
  * @internal
8
8
  */
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Reads the version declared by the package owning a directory, defaulting to this module's own, which is
3
3
  * this package whether it runs from source under the test runner or from the build output once installed.
4
- * Throws where the owning manifest declares no string version.
4
+ * Throws when the owning manifest declares no string version.
5
5
  *
6
6
  * @internal
7
7
  */
@@ -1,6 +1,6 @@
1
1
  /**
2
- * Runs the `tb-git` command line, returning what to write and exit with rather than doing either, so the
3
- * whole surface is exercisable without a process. Every failure is reported through the result: Nothing throws.
2
+ * Runs the `tb-git` command line, returning what to write and exit with rather than doing either, so that
3
+ * the whole surface is exercisable without a process. Every failure is reported through the result: Nothing throws.
4
4
  *
5
5
  * @internal
6
6
  */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@williamthorsen/toolbelt.git",
3
- "version": "0.4.0",
3
+ "version": "0.4.2",
4
4
  "description": "Utilities for working with git",
5
5
  "keywords": [
6
6
  "esm",
@@ -45,10 +45,10 @@
45
45
  "dist/*"
46
46
  ],
47
47
  "dependencies": {
48
- "@williamthorsen/toolbelt.strings": "8.0.0"
48
+ "@williamthorsen/toolbelt.strings": "8.0.2"
49
49
  },
50
50
  "devDependencies": {
51
- "@williamthorsen/toolbelt.testing": "0.6.0"
51
+ "@williamthorsen/toolbelt.testing": "0.6.2"
52
52
  },
53
53
  "engines": {
54
54
  "node": ">=24.0.0"