@williamthorsen/toolbelt.git 0.4.1 → 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,13 @@
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
+
5
12
  ## 0.4.1 — 2026-09-17
6
13
 
7
14
  ### Dependency updates
package/README.md CHANGED
@@ -14,7 +14,7 @@ Requires Node.js 24 or later.
14
14
 
15
15
  ## CLI
16
16
 
17
- 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.
18
18
 
19
19
  ```sh
20
20
  pnpm add --global @williamthorsen/toolbelt.git # puts tb-git on PATH
@@ -41,7 +41,7 @@ tb-git branch-number 232_add-widget --min 3000 --max 3999
41
41
  # 3232
42
42
  ```
43
43
 
44
- 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.
45
45
 
46
46
  ### `tb-git ticket-ref [<branch>] [options]`
47
47
 
@@ -72,7 +72,7 @@ With no `<branch>`, both subcommands resolve the checked-out branch with `git br
72
72
  | `1` | `ticket-ref` found no ticket in the branch name; both streams are empty |
73
73
  | `2` | Usage or validation error, with the message on stderr |
74
74
 
75
- 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`.
76
76
 
77
77
  ```sh
78
78
  if ref=$(tb-git ticket-ref); then
@@ -105,11 +105,11 @@ findBranchTicketRef('232_add-widget');
105
105
  // { id: '232', number: 232 }
106
106
  ```
107
107
 
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 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.
109
109
 
110
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`.
111
111
 
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 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.
113
113
 
114
114
  ```ts
115
115
  findBranchTicketRef('mac-22/add-widget');
@@ -144,7 +144,7 @@ deriveBranchNumber('main');
144
144
  // 663286764
145
145
  ```
146
146
 
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 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.
148
148
 
149
149
  ```ts
150
150
  deriveBranchNumber('232_add-widget', { min: 3000, max: 3999 });
@@ -154,4 +154,4 @@ deriveBranchNumber('refactor/tidy-imports', { min: 3000, max: 3999 });
154
154
  // 3508
155
155
  ```
156
156
 
157
- 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.1",
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.1"
48
+ "@williamthorsen/toolbelt.strings": "8.0.2"
49
49
  },
50
50
  "devDependencies": {
51
- "@williamthorsen/toolbelt.testing": "0.6.1"
51
+ "@williamthorsen/toolbelt.testing": "0.6.2"
52
52
  },
53
53
  "engines": {
54
54
  "node": ">=24.0.0"