@williamthorsen/toolbelt.numbers 7.0.3 → 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.34.0";
+export const __readyupVersion = "0.36.0";
 
 
 // ../adoption/src/conventions/path-predicates.ts
@@ -50,12 +50,17 @@ import {
   countPackageUsage,
   readTrackedSources
 } from "readyup/check-utils";
-var NOT_A_REPO = "the project is not a git working tree, and these checks read the files git tracks";
+var NOT_A_REPO = "the project is not a git working tree, and these checks read the files that git tracks";
 var NOTHING_TO_REPORT = { findings: [] };
 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";
 
@@ -273,8 +303,8 @@ var default_default = defineAdoptionKit({
   exportNames: ADOPTED_EXPORTS,
   noSourcesReason: "the project holds 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 is what keeps
-  // its build-first message alive through an incomplete install.
+  // A test computes these values deliberately, and a bootstrap wrapper's hand-rolled arithmetic keeps its
+  // build-first message alive through an incomplete install.
   pathFilter: isAdoptableSource,
   checks: [
     {
@@ -289,7 +319,7 @@ var default_default = defineAdoptionKit({
       id: "no-hand-rolled-round",
       kinds: ["round-scale"],
       severity: "recommend",
-      fix: `Replace each expression named above with round from ${PACKAGE_NAME}/candidate, called as round(value, places). The substitution is exact: round scales by the same power of ten these sites write out. Reference: ${README_URL}`
+      fix: `Replace each expression named above with round from ${PACKAGE_NAME}/candidate, called as round(value, places). The substitution is exact: round scales by the same power of ten that these sites write out. Reference: ${README_URL}`
     },
     {
       name: "No source derives a random integer by hand",

package/.readyup/manifest.json

@@ -9,82 +9,97 @@
       "esbuildVersion": "0.28.2",
       "inputs": [
         {
-          "hash": "9cbd3541",
+          "hash": "1dc83619",
           "kind": "module",
           "path": "../../adoption/src/conventions/path-predicates.ts"
         },
         {
-          "hash": "c7d90b66",
+          "hash": "0237a871",
           "kind": "module",
           "path": "../../adoption/src/conventions/site-handoffs.ts"
         },
         {
-          "hash": "3a124dad",
+          "hash": "8fb83c2d",
           "kind": "module",
           "path": "../../adoption/src/kits/defineAdoptionKit.ts"
         },
         {
-          "hash": "6e5a8dda",
+          "hash": "10596562",
           "kind": "module",
           "path": "../../adoption/src/mod.ts"
         },
         {
-          "hash": "e8d0444d",
+          "hash": "6fdaacac",
           "kind": "module",
           "path": "../../adoption/src/portable/condenseWhitespace.ts"
         },
         {
-          "hash": "b6d99ce7",
+          "hash": "0661f0dd",
+          "kind": "module",
+          "path": "../../adoption/src/portable/listDirectoryAscents.ts"
+        },
+        {
+          "hash": "07c8358f",
           "kind": "module",
           "path": "../../adoption/src/portable/listFunctionBodies.ts"
         },
         {
-          "hash": "4d2d8e11",
+          "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"
         },
         {
-          "hash": "e6df5682",
+          "hash": "e9427d50",
+          "kind": "module",
+          "path": "../../adoption/src/portable/readLiteral.ts"
+        },
+        {
+          "hash": "24f6e6db",
           "kind": "module",
           "path": "kits/default.ts"
         },
         {
-          "hash": "f3d9105b",
+          "hash": "05bd292b",
           "kind": "module",
           "path": "../src/readiness/adoptedExports.ts"
         },
         {
-          "hash": "54ee66e5",
+          "hash": "f14085f3",
           "kind": "module",
           "path": "../src/readiness/listClampNestLines.ts"
         },
         {
-          "hash": "47d35285",
+          "hash": "eabb769f",
           "kind": "module",
           "path": "../src/readiness/listMathIdioms.ts"
         },
         {
-          "hash": "fa0a23b7",
+          "hash": "827c07b2",
           "kind": "module",
           "path": "../src/readiness/listRandomIntegerLines.ts"
         },
         {
-          "hash": "ae0ac903",
+          "hash": "bdcac255",
           "kind": "module",
           "path": "../src/readiness/listRoundScaleLines.ts"
         }
       ],
       "name": "default",
       "path": "kits/default.js",
-      "readyupVersion": "0.34.0",
+      "readyupVersion": "0.36.0",
       "source": "kits/default.ts",
-      "sourceHash": "e6df5682",
-      "targetHash": "44b320aa"
+      "sourceHash": "24f6e6db",
+      "targetHash": "b1603ae6"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,9 +2,115 @@
 
 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
+
+- Add a ReadyUp adoption kit (#253)
+
+  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`.
+
+- Add a ReadyUp adoption kit reporting hand-rolled sleeps (#303)
+
+  - Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.async` that recommends the use of `delay` to replace a hand-rolled sleep.
+
+### 📚 Documentation
+
+- Document the generated-source exemption in the adoption kits (#251)
+
+  Documents the generated- and vendored-source exemption in the `errors`, `numbers`, and `strings` READMEs.
+
+- Repair reduced object relatives in passages recurring across files (#262)
+
+  Repairs the reduced object relative in the prose passages that recur across more than one file, in package READMEs, source comments, test titles, and the ReadyUp kits' check messages.
+
+- Repair reduced object relatives in the READMEs and AGENTS.md (#263)
+
+  Repairs the reduced object relative in `AGENTS.md`, the root `README.md`, and the package READMEs.
+
+- Repair reduced object relatives in packages/adoption (#264)
+
+  Repairs the reduced object relative in `packages/adoption`, in source comments, doc descriptions, and test titles.
+
+- Repair reduced object relatives in the readiness modules and kits (#265)
+
+  Repairs the reduced object relative in the six kit-bearing packages' readiness modules and ReadyUp kit sources, across comments, doc descriptions, test titles, and the kits' check messages.
+
+- Repair the repository's prose and record every rejection's ground (#290)
+
+  Applies one repo-wide `revise-prose` sweep across the repository's READMEs, `AGENTS.md`, source comments, doc descriptions, and test names.
+
 ## 7.0.3 — 2026-08-30
 
-### Bug fixes
+### 🐛 Bug fixes
 
 - Reject a check declaring a kind its detector never produces (#246)
 
@@ -12,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)
 
@@ -34,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)
 
@@ -50,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)
 
@@ -62,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)
@@ -89,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)
 
@@ -107,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)
@@ -126,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)
 
@@ -146,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)
 
@@ -182,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)
 
@@ -190,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)
 
@@ -262,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,15 +1,46 @@
+<!-- readme-type: library -->
+
 # @williamthorsen/toolbelt.numbers
 
 Utility functions for working with numbers.
 
 <!-- section:release-notes -->
-## Release notes — v7.0.3 (2026-08-30)
+## 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.
+
+### 🐛 Bug fixes
+
+- Stop reading each segment of a probe's path as a separately probed name (#320)
 
-### Bug fixes
+  - 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`.
 
-- Reject a check declaring a kind its detector never produces (#246)
+- Make pickInteger draw once per call and keep seeded draws below 1 (#329)
 
-  Fixes an issue where an adoption check could declare a kind its kit's detector never produces. `Kind` was inferred from `checks` and `detect` together, so a typo in a check's `kinds` widened `Kind` rather than failing.
+  - 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
@@ -28,7 +59,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 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. 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.
 
 ```ts
 import { clamp } from '@williamthorsen/toolbelt.numbers/candidate';
@@ -57,9 +88,9 @@ 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 is what 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 })`.
+Mind the bound when replacing `Math.floor(Math.random() * n)`: That idiom stops at `n - 1`, so the equivalent is `pickInteger({ max: n - 1 })`.
 
 ```ts
 import { pickInteger } from '@williamthorsen/toolbelt.numbers/candidate';
@@ -75,11 +106,11 @@ The package ships a ReadyUp kit, so a project that installs it can ask how far i
 rdy run --packages
 ```
 
-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 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. All three report 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.
+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.
 
 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:
 

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

@@ -1,2 +1,7 @@
-import type { Seed } from '../internal/evaluateSeed.js';
+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.
+ */
 export declare function makeRng(seed?: Seed): () => number;

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

@@ -1,3 +1,11 @@
+/**
+ * Returns the value constrained to the inclusive bounds; an omitted bound leaves that side unconstrained.
+ * A NaN value passes through, but a NaN bound or a min greater than max throws a RangeError.
+ *
+ * @category Number
+ * @experimental
+ * @stage candidate
+ */
 export declare function clamp(value: number, bounds: ClampBounds): number;
 export interface ClampBounds {
     readonly max?: number | undefined;

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

@@ -1,4 +1,11 @@
-import type { Seed } from '../internal/evaluateSeed.js';
+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 {
     max?: number | undefined;

package/dist/esm/3-candidate/integer-string.d.ts

@@ -1,4 +1,23 @@
 import type { Maybe } from '../internal/internal.types.js';
+/**
+ * Returns true if the value is a string that represents a valid integer.
+ *
+ * @category Type Guards
+ * @experimental
+ * @stage candidate
+ */
 export declare function isIntegerString(value: string | null | undefined): value is string;
+/**
+ * Attempts to parse an integer from a string and returns the parsed integer.
+ * If the input does not represent a valid integer, returns the fallback value or throws the fallback error.
+ *
+ * @param value - The string to parse.
+ * @param fallback - The value to return if parsing fails.
+ * @returns The parsed integer or the fallback value.
+ *
+ * @category Type Guards
+ * @experimental
+ * @stage candidate
+ */
 export declare function safeParseInteger(value: Maybe<string>, fallback: number | Error): number;
 export declare function safeParseInteger(value: Maybe<string>, fallback?: undefined): number | undefined;

package/dist/esm/3-candidate/numeric-string.d.ts

@@ -1,4 +1,25 @@
 import type { Maybe } from '../internal/internal.types.js';
+/**
+ * Returns true if the value is a string that represents a valid finite number.
+ *
+ * Accepts integers, decimals, and scientific notation (e.g., "1e3").
+ *
+ * @category Type Guards
+ * @experimental
+ * @stage candidate
+ */
 export declare function isNumericString(value: string | null | undefined): value is string;
+/**
+ * Attempts to parse a number from a string and returns the parsed number.
+ * If the input does not represent a valid number, returns the fallback value or throws the fallback error.
+ *
+ * @param value - The string to parse.
+ * @param fallback - The value to return if parsing fails.
+ * @returns The parsed number or the fallback value.
+ *
+ * @category Type Guards
+ * @experimental
+ * @stage candidate
+ */
 export declare function safeParseNumber(value: Maybe<string>, fallback: number | Error): number;
 export declare function safeParseNumber(value: Maybe<string>, fallback?: undefined): number | undefined;

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

@@ -1,4 +1,14 @@
 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 {
     max?: number | undefined;

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

@@ -1 +1,10 @@
+/**
+ * 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,9 +1,27 @@
+/**
+ * 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;
     max: number;
 }
+/**
+ * Represents a range of integers. Non-integer values should be truncated by the called function.
+ */
 interface IntegerRange {
     min: number;
     max: number;

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

@@ -1,24 +1,46 @@
-import type { Seed, SeededGenerator } from '../internal/evaluateSeed.js';
+import { type Seed, type SeededGenerator } from '../internal/evaluateSeed.js';
+/**
+ * Class that manages a pseudo-random number generator that behaves deterministically when given a seed.
+ */
 export declare class SeededRng implements SeededGenerator {
     private _seed;
     private baseSeed;
     private nIncrements;
+    /**
+     * Constructor
+     */
     constructor(seed?: Seed);
     get maxBase(): number;
     get rng(): () => number;
     get seed(): number;
     static evaluateSeed(seed?: Seed): number | undefined;
+    /**
+     * Creates a child from a seed without mutating the parent seed.
+     */
     static clone<T extends ThisConstructor<typeof SeededRng>>(this: T, seed: undefined, nIncrements?: number): undefined;
     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.
+     */
     static cloneOrCreate<T extends ThisConstructor<typeof SeededRng>>(this: T, seed?: Seed, nIncrements?: number): This<T>;
     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.
+     * 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;
     clone<T extends SeededRng>(this: T, nIncrements?: number): T;
+    /** Safely increments the seed by the given number of increments */
     increment(nIncrements?: number): this;
     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;
     scaleDownSeed(seed: number): number;
     scaleUpSeed(value: number): number;

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

@@ -1,3 +1,8 @@
+/**
+ * Wrapper for `toIntegerSeed` that provides static properties for generating new seeds.
+ *
+ * @internal
+ */
 export declare const IntegerSeed: {
     max: number;
     multiplier: number;

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

@@ -1 +1,6 @@
+/**
+ * Deterministically computes and returns a number in the range [0, 1) based on the input.
+ *
+ * @internal
+ */
 export declare function computeFakeMathRandom(seed: number): 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/dist/esm/internal/evaluateSeed.d.ts

@@ -1,5 +1,18 @@
+/**
+ * Resolves a seed to its numeric value, returning `undefined` when there is no seed.
+ *
+ * @internal
+ */
 export declare function evaluateSeed(seed: Seed | undefined): number | undefined;
+/**
+ * Narrows a seed to a generator.
+ *
+ * @internal
+ */
 export declare function checkIsRngLike(seed: Seed | undefined): seed is SeededGenerator;
+/**
+ * Interface describing an object that returns a sequence of numbers.
+ */
 export interface SeededGenerator {
     seed: number;
     next(): number;

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

@@ -1 +1,6 @@
+/**
+ * Returns the sum of the given addends, wrapping around from 0 when the given max is exceeded.
+ *
+ * @internal
+ */
 export declare function wrapSum(max: number, ...addends: number[]): number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/toolbelt.numbers",
-  "version": "7.0.3",
+  "version": "7.2.0",
   "description": "Utility functions for working with numbers",
   "keywords": [
     "esm",
@@ -46,10 +46,10 @@
     "CHANGELOG.md"
   ],
   "devDependencies": {
-    "esbuild": "0.28.2",
-    "readyup": "0.34.0",
     "@williamthorsen/toolbelt.adoption": "0.1.0",
-    "@williamthorsen/toolbelt.testing": "0.5.0"
+    "@williamthorsen/toolbelt.testing": "0.6.0",
+    "esbuild": "0.28.2",
+    "readyup": "0.36.0"
   },
   "engines": {
     "node": ">=24.0.0"