@williamthorsen/toolbelt.numbers 7.2.1 → 7.2.3

package/.readyup/kits/default.js

@@ -1,6 +1,6 @@
 /** @noformat -- @generated. Do not edit. Compiled by rdy. */
 /* eslint-disable */
-export const __readyupVersion = "0.37.0";
+export const __readyupVersion = "0.40.0";
 
 
 // ../adoption/src/conventions/path-predicates.ts
@@ -301,7 +301,7 @@ var default_default = defineAdoptionKit({
   description: `Adoption checks for a project consuming ${PACKAGE_NAME}`,
   detect: listMathIdioms,
   exportNames: ADOPTED_EXPORTS,
-  noSourcesReason: "the project holds no JavaScript or TypeScript sources outside the exempt paths",
+  noSourcesReason: "the project contains no JavaScript or TypeScript sources outside the exempt paths",
   packageName: PACKAGE_NAME,
   // A test computes these values deliberately, and a bootstrap wrapper's hand-rolled arithmetic keeps its
   // build-first message alive through an incomplete install.
@@ -312,7 +312,7 @@ var default_default = defineAdoptionKit({
       id: "no-hand-rolled-clamp",
       kinds: ["clamp-nest"],
       severity: "recommend",
-      fix: `Replace each expression named above with clamp from ${PACKAGE_NAME}/candidate, called as clamp(value, { min, max }). It is not a silent substitution: clamp throws a RangeError on a reversed range or a NaN bound, where the nested Math calls return a value for both. Reference: ${README_URL}`
+      fix: `Replace each expression named above with clamp from ${PACKAGE_NAME}/candidate, called as clamp(value, { min, max }). It is not a silent substitution: clamp throws a RangeError on a reversed range or a NaN bound, whereas the nested Math calls return a value for both. Reference: ${README_URL}`
     },
     {
       name: "No source rounds to decimal places by hand",
@@ -326,7 +326,7 @@ var default_default = defineAdoptionKit({
       id: "no-hand-rolled-random-integer",
       kinds: ["random-integer"],
       severity: "recommend",
-      fix: `Replace each expression named above with pickInteger from ${PACKAGE_NAME}/candidate, which also takes a seed. Mind the bound: Math.floor(Math.random() * N) stops at N - 1, where pickInteger's max is inclusive, so the replacement is pickInteger({ max: N - 1 }). A site indexing an array is left to toolbelt.arrays, whose pickItem covers it. Reference: ${README_URL}`
+      fix: `Replace each expression named above with pickInteger from ${PACKAGE_NAME}/candidate, which also takes a seed. Mind the bound: Math.floor(Math.random() * N) stops at N - 1, whereas pickInteger's max is inclusive, so the replacement is pickInteger({ max: N - 1 }). A site indexing an array is left to toolbelt.arrays, whose pickItem covers it. Reference: ${README_URL}`
     }
   ]
 });

package/.readyup/manifest.json

@@ -9,22 +9,22 @@
       "esbuildVersion": "0.28.2",
       "inputs": [
         {
-          "hash": "1dc83619",
+          "hash": "fcd04dfa",
           "kind": "module",
           "path": "../../adoption/src/conventions/path-predicates.ts"
         },
         {
-          "hash": "0237a871",
+          "hash": "921ba938",
           "kind": "module",
           "path": "../../adoption/src/conventions/site-handoffs.ts"
         },
         {
-          "hash": "8fb83c2d",
+          "hash": "e6e87602",
           "kind": "module",
           "path": "../../adoption/src/kits/defineAdoptionKit.ts"
         },
         {
-          "hash": "10596562",
+          "hash": "09840c67",
           "kind": "module",
           "path": "../../adoption/src/mod.ts"
         },
@@ -34,37 +34,37 @@
           "path": "../../adoption/src/portable/condenseWhitespace.ts"
         },
         {
-          "hash": "0661f0dd",
+          "hash": "3867c304",
           "kind": "module",
           "path": "../../adoption/src/portable/listDirectoryAscents.ts"
         },
         {
-          "hash": "07c8358f",
+          "hash": "982f3e6d",
           "kind": "module",
           "path": "../../adoption/src/portable/listFunctionBodies.ts"
         },
         {
-          "hash": "2d9f1edb",
+          "hash": "ce2e063d",
           "kind": "module",
           "path": "../../adoption/src/portable/listTemplateLiterals.ts"
         },
         {
-          "hash": "b0751395",
+          "hash": "a5dc0993",
           "kind": "module",
           "path": "../../adoption/src/portable/readAnchoredWindow.ts"
         },
         {
-          "hash": "0eb1daf1",
+          "hash": "9ff7cd2c",
           "kind": "module",
           "path": "../../adoption/src/portable/readBalancedGroup.ts"
         },
         {
-          "hash": "e9427d50",
+          "hash": "81846f1a",
           "kind": "module",
           "path": "../../adoption/src/portable/readLiteral.ts"
         },
         {
-          "hash": "24f6e6db",
+          "hash": "eecd2c1e",
           "kind": "module",
           "path": "kits/default.ts"
         },
@@ -74,32 +74,32 @@
           "path": "../src/readiness/adoptedExports.ts"
         },
         {
-          "hash": "f14085f3",
+          "hash": "67b9483f",
           "kind": "module",
           "path": "../src/readiness/listClampNestLines.ts"
         },
         {
-          "hash": "eabb769f",
+          "hash": "a80a25c8",
           "kind": "module",
           "path": "../src/readiness/listMathIdioms.ts"
         },
         {
-          "hash": "827c07b2",
+          "hash": "e7ef3938",
           "kind": "module",
           "path": "../src/readiness/listRandomIntegerLines.ts"
         },
         {
-          "hash": "bdcac255",
+          "hash": "3a93c656",
           "kind": "module",
           "path": "../src/readiness/listRoundScaleLines.ts"
         }
       ],
       "name": "default",
       "path": "kits/default.js",
-      "readyupVersion": "0.37.0",
+      "readyupVersion": "0.40.0",
       "source": "kits/default.ts",
-      "sourceHash": "24f6e6db",
-      "targetHash": "55bc7a45"
+      "sourceHash": "eecd2c1e",
+      "targetHash": "3296a47b"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## 7.2.3 — 2026-10-09
+
+### 📚 Documentation
+
+- Updates each kit README to show `rdy run --sources` and a `sources: ['npm:…']` config example, and states that this spelling needs readyup 0.40.0 or later. (#371)
+
+## 7.2.2 — 2026-10-02
+
+### 📚 Documentation
+
+- 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)
+- Adds `@category` tags to 50 exported tier functions and classes, and `@stage` tags to the 49 of them that lacked one, which puts those 49 under the check in `stage-tag-alignment`. (#353)
+- Revises READMEs, doc comments, and test names across the repository to follow the current `plain-speech` and writing-preference rules. (#354)
+- 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)
+
 ## 7.2.0 — 2026-09-15
 
 ### 🎉 Features
@@ -284,6 +299,50 @@ All notable changes to this project will be documented in this file.
 
 ### 📦 Dependencies
 
+- Adapt to dependency upgrades and bump Node engine to >=24 (#8)
+
+  Upgrades all dependencies to their latest versions, bumps the Node.js engine requirement from >=18.17.0 to >=24.0.0 across all 13 workspace packages, and adapts source code to satisfy new lint rules introduced by the upgraded ESLint plugins. Also upgrades `@williamthorsen/eslint-config-typescript` from 5.12.1 to 5.12.2 to fix ESM import issues in the compiled output.
+
+  Commit details:
+
+  - root|deps: Upgrade all deps to latest version
+
+  - root|refactor: Fix lint
+
+  - root|deps: Upgrade all deps to latest minor version
+
+  - root|deps: Allow unpatchable vulns in dev deps
+
+  - root|refactor: Adapt to dependency upgrades and bump Node engine to >=24
+  * Upgrade eslint-config-typescript to 5.12.2 (fixes ESM import issues, removes need for pnpm patch)
+  * Bump engines.node from >=18.17.0 to >=24.0.0 across all packages
+  * Update CI to Node 24.14.0 and pnpm 10.30.3
+  * Replace .sort() with .toSorted() to satisfy unicorn/no-array-sort
+  * Fix lint errors: remove useless default assignments, redundant type constituents, deprecated re-exports, and empty array args to Set constructor
+  - datetime|tests: Fix locale mismatch in Timestamp test
+
+  Pass the same 'en-US' locale to both the expected-value computation and
+  the method under test. Previously the test used the system default locale
+  for the expected value but explicit 'en-US' for the actual call, which
+  diverged under Node 24's updated Intl formatting.
+
+  - root|refactor: Replace toThrow with toThrowError across all tests
+
+  The vitest/no-alias-methods rule in strict-lint requires the canonical
+  toThrowError() name instead of the toThrow() alias.
+
+  - root|refactor: Fix remaining strict-lint errors
+  * Use import() in vi.mock for vitest/prefer-import-in-mock
+  * Replace expect(typeof x).toBe() with expectTypeOf for vitest/prefer-expect-type-of
+  * Use String.raw for regex escapes for unicorn/prefer-string-raw
+  - root|tooling: Use ws runner to fix recursive build command
+
+  The build script used `pnpm --recursive run build` but no workspace package defines a `build` script — they all use `ws build` through the workspace script runner. Aligns with all other recursive commands.
+
+## 4.3.0 — 2026-03-08
+
+### 📦 Dependencies
+
 - Adapt to dependency upgrades and bump Node engine to >=24 (#8)
 
   Upgrades all dependencies to their latest versions, bumps the Node.js engine requirement from >=18.17.0 to >=24.0.0 across all 13 workspace packages, and adapts source code to satisfy new lint rules introduced by the upgraded ESLint plugins. Also upgrades `@williamthorsen/eslint-config-typescript` from 5.12.1 to 5.12.2 to fix ESM import issues in the compiled output.

package/README.md

@@ -22,7 +22,7 @@ Requires Node.js 24 or later.
 clamp(value: number, bounds: { min?: number; max?: number }): number;
 ```
 
-Returns the value constrained to the inclusive bounds; an omitted bound leaves that side unconstrained. A reversed range or a `NaN` bound throws a `RangeError`, where the `Math.max(min, Math.min(max, value))` idiom that it replaces returns a value for both. A `NaN` value passes through.
+Returns the value constrained to the inclusive bounds; an omitted bound leaves that side unconstrained. `clamp` throws a `RangeError` for a reversed range or a `NaN` bound, whereas the `Math.max(min, Math.min(max, value))` idiom that it replaces returns a value for both. It passes a `NaN` value through.
 
 ```ts
 import { clamp } from '@williamthorsen/toolbelt.numbers/candidate';
@@ -37,7 +37,7 @@ clamp(-5, { min: 0 }); // 0
 round(value: number, nDecimalPlaces?: number): number;
 ```
 
-Returns the value rounded to the given number of decimal places, or to a whole number where none is given.
+Returns the value rounded to the given number of decimal places, or to a whole number when none is given.
 
 ```ts
 import { round } from '@williamthorsen/toolbelt.numbers/candidate';
@@ -63,17 +63,17 @@ pickInteger({ min: 1, max: 6 }); // 1 through 6
 
 ## Adoption checks
 
-The package ships a ReadyUp kit, so a project that installs it can ask how far its adoption got:
+The package includes a ReadyUp kit. A project that installs it can ask how far its adoption got:
 
 ```sh
-rdy run --packages
+rdy run --sources
 ```
 
-The kit reads the project's tracked sources and reports every hand-rolled clamp, decimal rounding, and random integer in them, each counted against the calls that the project already makes into this package. All three report at `recommend`: They are correct code that a published utility expresses better, not defects.
+The kit reads the project's tracked sources and reports every hand-rolled clamp, decimal rounding, and random integer in them, each counted against the calls that the project already makes into this package. The kit reports all three at `recommend`: They are correct code that a published utility expresses better, not defects.
 
 A random integer used as an array subscript is left alone. That site belongs to `@williamthorsen/toolbelt.arrays`, whose `pickItem` covers it, and reporting it here would mean seeing one line twice under conflicting advice.
 
-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 compute these values 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.
+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 compute these values 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.
 
 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:
 
@@ -82,10 +82,10 @@ A reviewed site is silenced by an `rdy-ignore` pragma on its own line, or `rdy-i
 const bounded = Math.max(min, Math.min(max, value));
 ```
 
-Add the package to `.config/readyup.config.ts` to include it in a routine sweep:
+Add the package to `.config/readyup.config.ts` to include it in a routine sweep, a spelling that readyup 0.40.0 or later reads:
 
 ```ts
 export default defineRdyConfig({
-  packages: ['@williamthorsen/toolbelt.numbers'],
+  sources: ['npm:@williamthorsen/toolbelt.numbers'],
 });
 ```

package/dist/esm/1-proposed/makeRng.d.ts

@@ -3,5 +3,9 @@ import { type Seed } from '../internal/evaluateSeed.js';
  * Returns a number generator whose output, when invoked successively, is a pseudo-random
  * series of numbers that deterministically depend on the initial seed (or pseudo-random if no seed is given).
  * This is not intended to be a cryptographically secure random number generator.
+ *
+ * @category Number
+ * @experimental
+ * @stage proposed
  */
 export declare function makeRng(seed?: Seed): () => number;

package/dist/esm/3-candidate/round.d.ts

@@ -1,5 +1,5 @@
 /**
- * Returns the number rounded to the given number of decimal places, or 0 if no nDecimalPlaces is specified.
+ * Returns the number rounded to the given number of decimal places.
  * @param value
  * @param nDecimalPlaces
  *

package/dist/esm/3-candidate/seeded-rng.d.ts

@@ -1,18 +1,24 @@
 import { type Seed, type SeededGenerator } from '../internal/evaluateSeed.js';
 /**
- * Class that manages a pseudo-random number generator that behaves deterministically when given a seed.
+ * A pseudo-random number generator that behaves deterministically when given a seed.
+ *
+ * @category Number
+ * @experimental
+ * @stage candidate
  */
 export declare class SeededRng implements SeededGenerator {
     private _seed;
     private baseSeed;
     private nIncrements;
-    /**
-     * Constructor
-     */
+    /** Creates a generator from the seed, or from a random seed when none is given. */
     constructor(seed?: Seed);
+    /** Returns the upper bound of the seed range, as an accessor because a static property cannot be overridden. */
     get maxBase(): number;
+    /** Returns a function that yields the next value on each call, sharing this instance's state. */
     get rng(): () => number;
+    /** Returns the current seed. */
     get seed(): number;
+    /** Resolves a seed-like value to a number. */
     static evaluateSeed(seed?: Seed): number | undefined;
     /**
      * Creates a child from a seed without mutating the parent seed.
@@ -21,36 +27,59 @@ export declare class SeededRng implements SeededGenerator {
     static clone<T extends ThisConstructor<typeof SeededRng>>(this: T, seed: Seed, nIncrements?: number): This<T>;
     static clone<T extends ThisConstructor<typeof SeededRng>>(this: T, seed: Seed | undefined, nIncrements?: number): This<T> | undefined;
     /**
-     * Clones the given seed or creates a new one if none is given.
+     * Clones the given seed, or creates a randomly seeded generator when none is given.
      */
     static cloneOrCreate<T extends ThisConstructor<typeof SeededRng>>(this: T, seed?: Seed, nIncrements?: number): This<T>;
+    /** Creates a child from a seed, advancing the seed when it is a generator. */
     static spawn<T extends ThisConstructor<typeof SeededRng>>(this: T, seed: undefined): undefined;
     static spawn<T extends ThisConstructor<typeof SeededRng>>(this: T, seed: Seed): This<T>;
     static spawn<T extends ThisConstructor<typeof SeededRng>>(this: T, seed: Seed | undefined): This<T> | undefined;
     /**
-     * Given a seed-accepting function and an optional seed, returns a new function that passes the seed to the function.
+     * Wraps a seed-accepting function so that every call passes it one generator spawned from the seed.
      * The spawned generator is an instance of the class on which the method is called, so subclasses supply their
      * own sequence.
      */
     static withSeed<TOptions extends object, R>(fn: (options?: OptionsWithSeed<TOptions> | OptionsWithSeed<EmptyObject>) => R, seed: Seed | undefined): (options?: TOptions) => R;
+    /** Returns a copy of this generator, advanced by the given number of increments. */
     clone<T extends SeededRng>(this: T, nIncrements?: number): T;
     /** Safely increments the seed by the given number of increments */
     increment(nIncrements?: number): this;
+    /** Returns the next value in the pseudo-random sequence, then advances the seed `n` times. */
     next(n?: number): number;
     /**
      * Returns the next value in the pseudo-random sequence without incrementing the seed.
      * For use in testing and debugging.
      */
     peek(): number;
+    /** Maps a seed from the full integer-seed range onto this generator's range. */
     scaleDownSeed(seed: number): number;
+    /** Maps a seed from this generator's range onto the full integer-seed range. */
     scaleUpSeed(value: number): number;
+    /** Returns the value derived from the current seed. */
     protected generateValue(): number;
+    /** Records the base seed, wrapped into range, and starts the current seed at it. */
     protected initializeSeeds(baseSeed?: number): void;
 }
+/**
+ * A `SeededRng` that returns integers in the range [1, Number.MAX_SAFE_INTEGER].
+ *
+ * @category Number
+ * @experimental
+ * @stage candidate
+ */
 export declare class IntSeededRng extends SeededRng {
+    /** Returns an integer derived from the current seed. */
     protected generateValue(): number;
 }
+/**
+ * A `SeededRng` that returns integers in the range [1, 2 ** 32 - 1].
+ *
+ * @category Number
+ * @experimental
+ * @stage candidate
+ */
 export declare class Int32SeededRng extends SeededRng {
+    /** Returns an integer derived from the current seed. */
     protected generateValue(): number;
 }
 type EmptyObject = Record<string, never> | Record<number, never>;

package/dist/esm/internal/IntegerSeed.d.ts

@@ -6,6 +6,8 @@
 export declare const IntegerSeed: {
     max: number;
     multiplier: number;
+    /** Converts a value to an integer seed, drawing a random value when none is given. */
     toInt(value?: number): number;
+    /** Returns the seed that follows the given one in the Lehmer sequence. */
     next(seed: number): number;
 };

package/dist/esm/internal/evaluateSeed.d.ts

@@ -11,7 +11,7 @@ export declare function evaluateSeed(seed: Seed | undefined): number | undefined
  */
 export declare function checkIsRngLike(seed: Seed | undefined): seed is SeededGenerator;
 /**
- * Interface describing an object that returns a sequence of numbers.
+ * An object that returns a sequence of numbers and exposes its current seed.
  */
 export interface SeededGenerator {
     seed: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/toolbelt.numbers",
-  "version": "7.2.1",
+  "version": "7.2.3",
   "description": "Utility functions for working with numbers",
   "keywords": [
     "esm",
@@ -47,9 +47,9 @@
   ],
   "devDependencies": {
     "@williamthorsen/toolbelt.adoption": "0.1.0",
-    "@williamthorsen/toolbelt.testing": "0.6.1",
+    "@williamthorsen/toolbelt.testing": "0.6.3",
     "esbuild": "0.28.2",
-    "readyup": "0.37.0"
+    "readyup": "0.40.0"
   },
   "engines": {
     "node": ">=24.0.0"