@williamthorsen/toolbelt.numbers 7.1.0 → 7.2.0

package/.readyup/kits/default.js

@@ -1,6 +1,6 @@
 /** @noformat -- @generated. Do not edit. Compiled by rdy. */
 /* eslint-disable */
-export const __readyupVersion = "0.35.0";
+export const __readyupVersion = "0.36.0";
 
 
 // ../adoption/src/conventions/path-predicates.ts
@@ -56,6 +56,11 @@ function defineAdoptionKit(spec) {
   assertCheckIdsAreUnique();
   const cache = {};
   const adoptedPackage = { exportNames: spec.exportNames, packageName: spec.packageName };
+  const kitScope = { noSourcesReason: spec.noSourcesReason, pathFilter: spec.pathFilter };
+  const pathFiltersByKind = mapPathFiltersByKind();
+  const sweptPathFilters = [
+    .../* @__PURE__ */ new Set([spec.pathFilter, ...spec.checks.map((check) => resolveScope(check).pathFilter)])
+  ];
   return defineRdyKit({
     description: spec.description,
     defaultSeverity: "warn",
@@ -66,7 +71,7 @@ function defineAdoptionKit(spec) {
           name: check.name,
           id: check.id,
           ...check.severity !== void 0 && { severity: check.severity },
-          skip: skipUnlessProjectHoldsSources,
+          skip: () => skipUnlessProjectHoldsSources(resolveScope(check)),
           check: () => reportKinds(check.kinds),
           fix: check.fix
         }))
@@ -85,16 +90,38 @@ function defineAdoptionKit(spec) {
       throw new Error(`${spec.packageName}'s kit gives one id to more than one check: ${ids}`);
     }
   }
+  function isSweptPath(path) {
+    return sweptPathFilters.some((pathFilter) => pathFilter(path));
+  }
   function loadSummary() {
     cache.summary ??= readProject();
     return cache.summary;
   }
+  function mapPathFiltersByKind() {
+    const pathFilters = /* @__PURE__ */ new Map();
+    const conflicted = /* @__PURE__ */ new Set();
+    for (const check of spec.checks) {
+      const { pathFilter } = resolveScope(check);
+      for (const kind of check.kinds) {
+        const assigned = pathFilters.get(kind);
+        if (assigned !== void 0 && assigned !== pathFilter) conflicted.add(kind);
+        pathFilters.set(kind, pathFilter);
+      }
+    }
+    if (conflicted.size > 0) {
+      const kinds = [...conflicted].toSorted().join(", ");
+      throw new Error(`${spec.packageName}'s kit reads one kind through more than one path filter: ${kinds}`);
+    }
+    return pathFilters;
+  }
   async function readProject() {
-    const sources = await readTrackedSources(spec.pathFilter);
+    const sources = await readTrackedSources(isSweptPath);
     if (sources === void 0) return void 0;
     return {
       adoptedCount: countPackageUsage(sources, adoptedPackage),
-      findings: sources.flatMap((source) => spec.detect(source.text).map((site) => ({ ...site, path: source.path }))),
+      findings: sources.flatMap(
+        (source) => spec.detect(source.text).filter((site) => (pathFiltersByKind.get(site.kind) ?? spec.pathFilter)(source.path)).map((site) => ({ ...site, path: source.path }))
+      ),
       sources
     };
   }
@@ -108,10 +135,13 @@ function defineAdoptionKit(spec) {
       shouldReport: (finding) => kinds.includes(finding.kind)
     });
   }
-  async function skipUnlessProjectHoldsSources() {
+  function resolveScope(check) {
+    return check.pathFilter === void 0 ? kitScope : { noSourcesReason: check.noSourcesReason, pathFilter: check.pathFilter };
+  }
+  async function skipUnlessProjectHoldsSources(scope) {
     const summary = await loadSummary();
     if (summary === void 0) return NOT_A_REPO;
-    return summary.sources.length === 0 ? spec.noSourcesReason : false;
+    return summary.sources.some((source) => scope.pathFilter(source.path)) ? false : scope.noSourcesReason;
   }
 }
 
@@ -120,6 +150,14 @@ function condenseWhitespace(text) {
   return text.replaceAll(/\s+/g, " ");
 }
 
+// ../adoption/src/portable/readAnchoredWindow.ts
+function readAnchoredWindow(source, offset, lengths) {
+  return {
+    after: condenseWhitespace(source.slice(offset, offset + lengths.lookahead)),
+    before: condenseWhitespace(source.slice(Math.max(0, offset - lengths.lookbehind), offset))
+  };
+}
+
 // ../adoption/src/portable/readBalancedGroup.ts
 var PARENTHESES = { close: ")", open: "(" };
 function readBalancedGroup(source, from, delimiters) {
@@ -136,14 +174,6 @@ function readBalancedGroup(source, from, delimiters) {
   return void 0;
 }
 
-// ../adoption/src/portable/readAnchoredWindow.ts
-function readAnchoredWindow(source, offset, lengths) {
-  return {
-    after: condenseWhitespace(source.slice(offset, offset + lengths.lookahead)),
-    before: condenseWhitespace(source.slice(Math.max(0, offset - lengths.lookbehind), offset))
-  };
-}
-
 // ../adoption/src/mod.ts
 import { blankNonCode, getLineAtOffset } from "readyup/check-utils";
 

package/.readyup/manifest.json

@@ -9,22 +9,22 @@
       "esbuildVersion": "0.28.2",
       "inputs": [
         {
-          "hash": "b9007d48",
+          "hash": "1dc83619",
           "kind": "module",
           "path": "../../adoption/src/conventions/path-predicates.ts"
         },
         {
-          "hash": "84c99907",
+          "hash": "0237a871",
           "kind": "module",
           "path": "../../adoption/src/conventions/site-handoffs.ts"
         },
         {
-          "hash": "3372fb44",
+          "hash": "8fb83c2d",
           "kind": "module",
           "path": "../../adoption/src/kits/defineAdoptionKit.ts"
         },
         {
-          "hash": "dee2a3a3",
+          "hash": "10596562",
           "kind": "module",
           "path": "../../adoption/src/mod.ts"
         },
@@ -34,17 +34,27 @@
           "path": "../../adoption/src/portable/condenseWhitespace.ts"
         },
         {
-          "hash": "15a78157",
+          "hash": "0661f0dd",
+          "kind": "module",
+          "path": "../../adoption/src/portable/listDirectoryAscents.ts"
+        },
+        {
+          "hash": "07c8358f",
           "kind": "module",
           "path": "../../adoption/src/portable/listFunctionBodies.ts"
         },
         {
-          "hash": "1d2261fb",
+          "hash": "2d9f1edb",
+          "kind": "module",
+          "path": "../../adoption/src/portable/listTemplateLiterals.ts"
+        },
+        {
+          "hash": "b0751395",
           "kind": "module",
           "path": "../../adoption/src/portable/readAnchoredWindow.ts"
         },
         {
-          "hash": "498e3ca4",
+          "hash": "0eb1daf1",
           "kind": "module",
           "path": "../../adoption/src/portable/readBalancedGroup.ts"
         },
@@ -86,10 +96,10 @@
       ],
       "name": "default",
       "path": "kits/default.js",
-      "readyupVersion": "0.35.0",
+      "readyupVersion": "0.36.0",
       "source": "kits/default.ts",
       "sourceHash": "24f6e6db",
-      "targetHash": "cee2ac4e"
+      "targetHash": "b1603ae6"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,9 +2,77 @@
 
 All notable changes to this project will be documented in this file.
 
+## 7.2.0 — 2026-09-15
+
+### 🎉 Features
+
+- Add a ReadyUp adoption kit reporting hand-rolled guards (#311)
+
+  - Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.guards` that reports every function whose entire body re-implements a guard published by the package.
+
+- Add a ReadyUp adoption kit to toolbelt.filesystem (#316)
+
+  - Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.filesystem` that recommends `writeAtomic` where a project writes a file to a temporary path and renames it into place, and `listDirectoryChain`, `findDirectoryChainMatch`, or `listDirectoryChainMatches` where a loop ascends to the filesystem root by `path.dirname`.
+  - Promotes `writeAtomic` to the candidate tier.
+
+  Migration: Change any import of `writeAtomic` from `@williamthorsen/toolbelt.filesystem/proposed` to `@williamthorsen/toolbelt.filesystem/candidate`.
+
+- Read a directory walk's probed name through a binding or constant (#324)
+
+  - Extends the ReadyUp adoption kit in `@williamthorsen/toolbelt.packaging` to recommend `findPackageRoot` or `resolveSelfVersion` for a hand-rolled `package.json` search that checks for the file through a variable declared once inside its loop and never reassigned there, or through a string constant declared once in the same file.
+  - Stops the kit in `@williamthorsen/toolbelt.filesystem` from reporting such a search, which it previously treated as a generic directory walk.
+
+- Report hand-rolled dedents in the strings adoption kit (#330)
+
+  - Adds `no-joined-line-array`, which reports an array of string or template literals that spans several lines and is joined with a newline.
+  - Adds `no-layout-breaking-template`, which reports an untagged template literal whose later lines drop below the indentation of the line on which it opens.
+
+### 🐛 Bug fixes
+
+- Stop reading each segment of a probe's path as a separately probed name (#320)
+
+  - Fixes an issue in which `toolbelt.filesystem`'s ReadyUp adoption kit treated a loop over parent directories as a search for each directory's own `package.json` when the path checked at each level contained a `'package.json'` literal, as in `path.join(dir, 'node_modules', name, 'package.json')`, and so did not report the loop under `no-hand-rolled-directory-walk`.
+
+- Make pickInteger draw once per call and keep seeded draws below 1 (#329)
+
+  - Fixes seeded draws that could return exactly 1, outside the documented range of [0, 1): With seed `1_000_000_856_026_238`, `pickInteger({ min: 0, max: 9, seed })` returned 10 and `pickItem` from `toolbelt.arrays` threw a `RangeError`.
+  - Changes only the draw that returned 1, which no `SeededRng` and no integer seed below 2³¹ could produce.
+  - Stops `pickInteger` from skipping its draw when `min` and `max` truncate to the same integer, which changes no return value but shifts the later values drawn from a `SeededRng` or seed function passed with such bounds.
+
+### ♻️ Refactoring
+
+- Move directory-walk recognition from filesystem into packages/adoption (#318)
+
+  - Adds `listDirectoryAscents` to `packages/adoption`, which reports each directory ascent once with the names probed by its innermost loop, and reduces `filesystem`'s `listChainWalkSites` to a partition of that output, so a `toolbelt.packaging` kit can partition the same ascents without its own copy of the recognition.
+  - Renames the hand-off rule `isProjectRootSearch` to `isManifestSearch` and rewrites the text in `packages/adoption` and `filesystem` that credited `findProjectRoot` alone with a `package.json` walk.
+  - Stops `filesystem`'s kit from reporting a loop that ascends one binding around an inner loop ascending another binding and probing for `package.json`, which is the only finding changed by the move.
+
+### 🧪 Tests
+
+- Move the rdy run report reader into the adoption test utilities (#323)
+
+  - Replaces the `rdy run --json` report reader copied into each of the twelve `pragma-suppression.tool.test.ts` suites with `listKitCheckReports`, a helper added to `@williamthorsen/toolbelt.adoption/test-utils` that runs a package's compiled kit over a fixture repo and returns its check reports, so a change to the shape of readyup's report needs one edit rather than twelve.
+  - Fixes the error thrown for a kit that does not load: Each copy discarded the load error recorded by `rdy` on the kit's entry and threw "the run reported no adoption checks", and the helper throws with `rdy`'s own message instead.
+
+### ⚙️ Tooling
+
+- Remove the stale repo-local cliff.toml and normalize changelog titles (#327)
+
+  - Stops `release-kit prepare` from printing a "skipped due to grouping error(s)" warning for each releasable workspace by letting it resolve the git-cliff template bundled with release-kit, previously overridden by the root `cliff.toml`.
+  - Excludes commits without a ticket prefix from future changelog entries.
+  - Renames the section titles in every `packages/*/.meta/changelog.json`, except `Dependency updates`, to the headings of release-kit's work-type taxonomy, such as "🎉 Features" and "🏗️ Internal features", and regenerates each `CHANGELOG.md` so that release-kit orders existing and new sections by the same rule.
+  - Causes the next `release-kit prepare` to plan patch releases of `dstructs`, `hof`, and `sets`, which had no other commits since their last release, because the changelog commit touches every workspace.
+
+### 📚 Documentation
+
+- Align prose with plain-speech doctrine and writing conventions (#306)
+
+  - Copy-edits prose across the repo: comments, test names, package READMEs, and `AGENTS.md`.
+  - Rewrites a few user-facing strings as well, among them `configure-project`'s help text and the errors from `parseProjectSpec`, `securityCommands`, and `hashString`.
+
 ## 7.1.0 — 2026-09-06
 
-### Features
+### 🎉 Features
 
 - Add a ReadyUp adoption kit (#253)
 
@@ -14,12 +82,7 @@ All notable changes to this project will be documented in this file.
 
   - Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.async` that recommends the use of `delay` to replace a hand-rolled sleep.
 
-### Dependencies
-
-- Upgrade all deps to latest version
-- Upgrade all deps to latest version
-
-### Documentation
+### 📚 Documentation
 
 - Document the generated-source exemption in the adoption kits (#251)
 
@@ -47,7 +110,7 @@ All notable changes to this project will be documented in this file.
 
 ## 7.0.3 — 2026-08-30
 
-### Bug fixes
+### 🐛 Bug fixes
 
 - Reject a check declaring a kind its detector never produces (#246)
 
@@ -55,21 +118,15 @@ All notable changes to this project will be documented in this file.
 
 ## 7.0.2 — 2026-08-28
 
-### Refactoring
+### ♻️ Refactoring
 
 - Upgrade eslint-config-typescript to v12.0.1 and satisfy its new rules (#236)
 
   Upgrades `@williamthorsen/eslint-config-typescript` to v12 and fixes violations surfaced by the new rules banning unpublished barrels and floating disposables.
 
-### Dependencies
-
-- Upgrade all deps to latest version
-- Upgrade deps to latest version
-- Upgrade all deps to latest version
-
 ## 7.0.1 — 2026-08-24
 
-### Bug fixes
+### 🐛 Bug fixes
 
 - Stop the adoption kits from blanking code after `++`, `!`, and keyword-named members (#208)
 
@@ -77,7 +134,7 @@ All notable changes to this project will be documented in this file.
 
   `@williamthorsen/toolbelt.adoption` now takes `blankNonCode` and `getLineAtOffset` from `readyup/check-utils` in place of the copies it held, which had fallen behind readyup's on those three cases.
 
-### Internal
+### 🏗️ Internal features
 
 - Migrate the adoption kits onto FindingOutcome and add check ids (#217)
 
@@ -93,7 +150,7 @@ All notable changes to this project will be documented in this file.
 
 ## 7.0.0 — 2026-08-21
 
-### Features
+### 🎉 Features
 
 - 🚨 **Breaking:** Promote clamp to the candidate tier with a stricter bounds contract (#185)
 
@@ -105,25 +162,21 @@ All notable changes to this project will be documented in this file.
 
   Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.numbers`. When run against a project, the kit identifies hand-rolled code that can be replaced by the package's `clamp`, `round`, or `pickInteger` functions.
 
-### Bug fixes
+### 🐛 Bug fixes
 
 - Blank comments and literals before a detector reads a source (#191)
 
   Fixes the issue that the `errors`, `numbers`, and `vitest` adoption kits' detectors did not distinguish code from comments and literals, and so flagged a pattern written in a comment or a string as a candidate replacement site. Each detector now blanks every comment, string, template literal, and regular expression before its anchor scan, leaving interpolated expressions intact.
 
-### Refactoring
+### ♻️ Refactoring
 
 - Break the workspace dependency cycle by making `adoption` a leaf (#195)
 
   Fixes a cyclic dependency among packages in the repo. `packages/adoption` is now a workspace leaf: It declares no workspace dependency, and its test scaffolding is held to node builtins. A new root test fails on any cycle in the workspace dependency graph.
 
-### Dependencies
-
-- Upgrade all deps to latest version
-
 ## 6.0.1 — 2026-08-13
 
-### Tooling
+### ⚙️ Tooling
 
 - Remove redundant .gitignore files
 - Populate manifest metadata and adopt a pnpm catalog (#140)
@@ -132,13 +185,13 @@ All notable changes to this project will be documented in this file.
 
 ## 6.0.0 — 2026-08-12
 
-### Features
+### 🎉 Features
 
 - 🚨 **Breaking:** Rename get* functions by return kind and verb specificity (#119)
 
   Renames thirteen functions across various packages to align with a consistent naming pattern.
 
-### Refactoring
+### ♻️ Refactoring
 
 - Stop shipping test-only and dead support modules (#117)
 
@@ -150,17 +203,13 @@ All notable changes to this project will be documented in this file.
 
 ## 5.0.0 — 2026-08-08
 
-### Features
+### 🎉 Features
 
 - 🚨 **Breaking:** Spawn seeded number generator of same subclass (#84)
 
   A seeded generator spawned from a subclass now matches that subclass, so `IntSeededRng.withSeed` supplies the wrapped function integers where it previously supplied floats. Callers relying on values derived through that path must re-baseline. A detached reference such as `const { withSeed } = SeededRng` now throws.
 
-- Use underscore separator at 4 digits or more
-
-  Changes the `unicorn/numeric-separators-style` rule config so that separators are consistently used in base 10 numbers, instead of exempting numbers of 5 digits or less.
-
-### Refactoring
+### ♻️ Refactoring
 
 - Fixes violations surfaced by newly active lint rules (#84)
 - Fix slug punctuation and require safe integers (#86)
@@ -169,9 +218,7 @@ All notable changes to this project will be documented in this file.
   - Time-unit conversions, scaling range bounds, normal-distribution interval counts, and array indices in object paths now reject values too large to represent exactly instead of silently losing precision.
   - Seeded number generators now produce distinct sequences for seeds at or beyond 2^53, where adjacent seeds previously collapsed onto nearly identical output. A seed of that size saved before this release no longer reproduces the same output.
 
-- Fix lint
-
-### Tooling
+### ⚙️ Tooling
 
 - Migrate Vitest configs to the nmr projects model (#73)
 
@@ -189,35 +236,31 @@ All notable changes to this project will be documented in this file.
 
   All packages now have identical compiler settings, using the settings from the `@williamthorsen/tsconfig` base config without modification.
 
-### Dependencies
-
-- Upgrade all deps to latest version
-
 ## 4.3.8 — 2026-07-27
 
-### Tooling
+### ⚙️ Tooling
 
 - Normalize Vitest, and lint configs
 
-### Documentation
+### 📚 Documentation
 
 - Change license to ISC
 
 ## 4.3.7 — 2026-07-24
 
-### Tooling
+### ⚙️ Tooling
 
 - Configure release-kit & repo labels
 
 ## 4.3.6 — 2026-07-20
 
-### Bug fixes
+### 🐛 Bug fixes
 
 - Add repository field to package manifests for npm provenance (#65)
 
   Fixes an issue that prevented every package from publishing to npm. Each package now links to its source repository from its npm page.
 
-### Dependencies
+### 📦 Dependencies
 
 - Upgrade ESLint packages and migrate to TypeScript 6 (#67)
 
@@ -225,7 +268,7 @@ All notable changes to this project will be documented in this file.
 
 ## 4.3.5 — 2026-07-20
 
-### Tooling
+### ⚙️ Tooling
 
 - Migrate to the nmr toolchain and resolve dependency vulnerabilities (#45)
 
@@ -233,37 +276,13 @@ All notable changes to this project will be documented in this file.
 
 ## 4.3.4 — 2026-03-19
 
-### Formatting
+### 🎨 Formatting
 
 - Format changelogs
 
 ## 4.3.1 — 2026-03-10
 
-### Features
-
-- Add string functions
-- Add number functions
-- Add integer string functions
-- Caller can specify fallback value for safeParseInteger
-- Allow error as safeParseInteger fallback
-- Add safeParseNumber
-
-### Refactoring
-
-- Rename functions
-
-### Tests
-
-- Adapt Deno tests to Vitest
-
-### Tooling
-
-- Scaffold the numbers workspace
-- Enable incremental type generation
-- Rename publish script to avoid recursion
-- Change package registry from github to npmjs
-
-### Dependencies
+### 📦 Dependencies
 
 - Adapt to dependency upgrades and bump Node engine to >=24 (#8)
 
@@ -305,8 +324,4 @@ All notable changes to this project will be documented in this file.
 
   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.
 
-### Documentation
-
-- Fix lint
-
 <!-- Generated by release-kit. Do not edit this file. Use .meta/changelog-overrides.json to override entries. -->

package/README.md

@@ -1,19 +1,46 @@
+<!-- readme-type: library -->
+
 # @williamthorsen/toolbelt.numbers
 
 Utility functions for working with numbers.
 
 <!-- section:release-notes -->
-## Release notes — v7.1.0 (2026-09-06)
+## Release notes — v7.2.0 (2026-09-15)
+
+### 🎉 Features
+
+- Add a ReadyUp adoption kit reporting hand-rolled guards (#311)
+
+  - Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.guards` that reports every function whose entire body re-implements a guard published by the package.
+
+- Add a ReadyUp adoption kit to toolbelt.filesystem (#316)
+
+  - Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.filesystem` that recommends `writeAtomic` where a project writes a file to a temporary path and renames it into place, and `listDirectoryChain`, `findDirectoryChainMatch`, or `listDirectoryChainMatches` where a loop ascends to the filesystem root by `path.dirname`.
+  - Promotes `writeAtomic` to the candidate tier.
+
+  Migration: Change any import of `writeAtomic` from `@williamthorsen/toolbelt.filesystem/proposed` to `@williamthorsen/toolbelt.filesystem/candidate`.
+
+- Read a directory walk's probed name through a binding or constant (#324)
+
+  - Extends the ReadyUp adoption kit in `@williamthorsen/toolbelt.packaging` to recommend `findPackageRoot` or `resolveSelfVersion` for a hand-rolled `package.json` search that checks for the file through a variable declared once inside its loop and never reassigned there, or through a string constant declared once in the same file.
+  - Stops the kit in `@williamthorsen/toolbelt.filesystem` from reporting such a search, which it previously treated as a generic directory walk.
+
+- Report hand-rolled dedents in the strings adoption kit (#330)
+
+  - Adds `no-joined-line-array`, which reports an array of string or template literals that spans several lines and is joined with a newline.
+  - Adds `no-layout-breaking-template`, which reports an untagged template literal whose later lines drop below the indentation of the line on which it opens.
 
-### Features
+### 🐛 Bug fixes
 
-- Add a ReadyUp adoption kit (#253)
+- Stop reading each segment of a probe's path as a separately probed name (#320)
 
-  Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.objects`. The kit recommends `Object.hasOwn` or the package's own `hasOwnProperty` in place of a call reached through `Object.prototype`, and `isRecord` or `isRecordOrArray` in place of a guard written as `typeof value === 'object' && value !== null`. Its third check warns that a comparison of two `JSON.stringify` calls is key-order dependent and should be replaced by `isEqual`.
+  - Fixes an issue in which `toolbelt.filesystem`'s ReadyUp adoption kit treated a loop over parent directories as a search for each directory's own `package.json` when the path checked at each level contained a `'package.json'` literal, as in `path.join(dir, 'node_modules', name, 'package.json')`, and so did not report the loop under `no-hand-rolled-directory-walk`.
 
-- Add a ReadyUp adoption kit reporting hand-rolled sleeps (#303)
+- Make pickInteger draw once per call and keep seeded draws below 1 (#329)
 
-  - Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.async` that recommends the use of `delay` to replace a hand-rolled sleep.
+  - Fixes seeded draws that could return exactly 1, outside the documented range of [0, 1): With seed `1_000_000_856_026_238`, `pickInteger({ min: 0, max: 9, seed })` returned 10 and `pickItem` from `toolbelt.arrays` threw a `RangeError`.
+  - Changes only the draw that returned 1, which no `SeededRng` and no integer seed below 2³¹ could produce.
+  - Stops `pickInteger` from skipping its draw when `min` and `max` truncate to the same integer, which changes no return value but shifts the later values drawn from a `SeededRng` or seed function passed with such bounds.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -61,7 +88,7 @@ round(3.14159, 2); // 3.14
 pickInteger(params?: { min?: number; max?: number; seed?: Seed }): number;
 ```
 
-Returns a random integer between the bounds, **inclusive** of both, and truncates a non-integer bound. Passing a seed makes the draw deterministic, which a test wants.
+Returns a random integer between the bounds, **inclusive** of both, and truncates a non-integer bound. Passing a seed makes the draw deterministic, which a test wants. Each call draws exactly once, even when the bounds admit a single value.
 
 Mind the bound when replacing `Math.floor(Math.random() * n)`: That idiom stops at `n - 1`, so the equivalent is `pickInteger({ max: n - 1 })`.
 

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

@@ -1,6 +1,10 @@
 import { type Seed } from '../internal/evaluateSeed.js';
 /**
  * Returns a scaled random number in the range [min, max).
+ *
+ * @category Number
+ * @experimental
+ * @stage candidate
  */
 export declare function generateRandom(options?: Options): number;
 interface Options {

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

@@ -2,6 +2,12 @@ import type { Seed } from '../internal/evaluateSeed.js';
 /**
  * Returns a random integer between the bounds inclusive.
  * If the bounds are not integers, they are truncated to integers.
+ * Draws exactly once per call, even when the bounds admit a single value, so that a shared seed advances the same way
+ * whatever the bounds.
+ *
+ * @category Number
+ * @experimental
+ * @stage candidate
  */
 export declare function pickInteger(params?: Params): number;
 interface Params {

package/dist/esm/3-candidate/pickInteger.js

@@ -9,9 +9,6 @@ export function pickInteger(params = {}) {
     }
     const start = Math.trunc(Math.min(min, max));
     const end = Math.trunc(Math.max(min, max));
-    if (start === end) {
-        return start;
-    }
     const range = end - start + 1;
     return start + Math.floor(generateRandom({ seed }) * range);
 }

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

@@ -2,5 +2,9 @@
  * Returns the number rounded to the given number of decimal places, or 0 if no nDecimalPlaces is specified.
  * @param value
  * @param nDecimalPlaces
+ *
+ * @category Number
+ * @experimental
+ * @stage candidate
  */
 export declare function round(value: number, nDecimalPlaces?: number): number;

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

@@ -1,7 +1,19 @@
 /**
  * Scales a number from one range to another.
+ *
+ * @category Number
+ * @experimental
+ * @stage candidate
  */
 export declare function scale(value: number, toRange: Range, fromRange?: Partial<Range>): number;
+/**
+ * Scales a number from one range to another and rounds it to the nearest integer.
+ * Throws a RangeError unless the target bounds are safe integers.
+ *
+ * @category Number
+ * @experimental
+ * @stage candidate
+ */
 export declare function scaleInt(value: number, toRange: Range, fromRange?: Partial<IntegerRange>): number;
 interface Range {
     min: number;

package/dist/esm/internal/computeFakeMathRandom.js

@@ -11,5 +11,5 @@ export function computeFakeMathRandom(seed) {
     hash += hash << 3;
     hash ^= hash >> 11;
     hash += hash << 15;
-    return (hash & 0x7fff_ffff) / 0x7fff_ffff;
+    return Math.min(hash & 0x7fff_ffff, 0x7fff_fffe) / 0x7fff_ffff;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/toolbelt.numbers",
-  "version": "7.1.0",
+  "version": "7.2.0",
   "description": "Utility functions for working with numbers",
   "keywords": [
     "esm",
@@ -47,9 +47,9 @@
   ],
   "devDependencies": {
     "@williamthorsen/toolbelt.adoption": "0.1.0",
-    "@williamthorsen/toolbelt.testing": "0.5.1",
+    "@williamthorsen/toolbelt.testing": "0.6.0",
     "esbuild": "0.28.2",
-    "readyup": "0.35.0"
+    "readyup": "0.36.0"
   },
   "engines": {
     "node": ">=24.0.0"