@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 +7 -0
- package/README.md +7 -7
- package/bin/tb-git.js +3 -3
- package/dist/esm/3-candidate/findBranchTicketRef.d.ts +1 -1
- package/dist/esm/bin/findOwningManifest.d.ts +2 -2
- package/dist/esm/bin/resolveSelfVersion.d.ts +1 -1
- package/dist/esm/bin/runTbGit.d.ts +2 -2
- package/package.json +3 -3
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
|
|
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`
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
12
|
-
//
|
|
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
|
|
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
|
|
5
|
-
* the nearest
|
|
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
|
|
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
|
|
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.
|
|
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.
|
|
48
|
+
"@williamthorsen/toolbelt.strings": "8.0.2"
|
|
49
49
|
},
|
|
50
50
|
"devDependencies": {
|
|
51
|
-
"@williamthorsen/toolbelt.testing": "0.6.
|
|
51
|
+
"@williamthorsen/toolbelt.testing": "0.6.2"
|
|
52
52
|
},
|
|
53
53
|
"engines": {
|
|
54
54
|
"node": ">=24.0.0"
|