chore: clean-up

[Planeshifter]

Description

What is the purpose of this pull request?

This pull request:

• corrects a @param type in assert/is-well-formed-string that contradicts the function's own behavior, examples, and TypeScript declaration.
• fixes two typos in the @returns description of assert/is-ndarray-like-with-data-type.
• fixes an ungrammatical @returns description in assert/is-leap-year.
• adds a benchmark/benchmark.js to assert/is-node-repl, the only package in the namespace that exports a function but ships no benchmark.

Each is a separate commit. All four are documentation or benchmark additions; no observable behavior changes and no test expectations change.

assert/is-well-formed-string

The @param tag declared {string}, but the function accepts any value: the body is isPrimitive( str ) || isObject( str ), its own @example blocks pass [] and null documenting // returns false, and the package's docs/repl.txt and docs/types/index.d.ts already declare the parameter as any. The JSDoc was the only one of the package's three documentation layers that disagreed. Of the 220 assert packages documenting a single value argument, 220 use @param {*} and 219 describe it as "value to test". The two other packages declaring {string} — has-utf16-surrogate-pair-at and is-anagram — throw on non-string input and are correctly typed, so they are untouched.

assert/is-ndarray-like-with-data-type

The @returns description read "ndarray-lik object" and "data typee". The same sentence is spelled correctly in the package's own docs/types/index.d.ts and docs/repl.txt.

assert/is-leap-year

The @returns read "boolean whether a value corresponds to a leap year". "boolean whether" is ungrammatical and was the sole instance in the namespace; 297 of the 322 packages documenting a boolean return use "boolean indicating". The [value] optional marker is correct — the function branches on arguments.length and returns the current year's status when called with no arguments — and is left alone.

assert/is-node-repl

is-node-repl exports isNodeREPL(), a function, and had no benchmark/ directory. benchmark/benchmark.js is present in 303 of 348 assert packages (87.1%); narrowed to packages exporting a function rather than a precomputed value, is-node-repl was the sole omission. The call is not free — it walks the module.parent chain and, failing that, synthesizes and regex-tests a V8 stack trace — so it is measurably more expensive than the has-*-support probes, all 45 of which ship a benchmark. The new file follows that family's template. The commit also registers benchmark in the package.json directories field, as lint_package_json_files requires.

Related Issues

Does this pull request have any related issues?

No.

Questions

Any questions for reviewers of this pull request?

Three, all concerning findings deliberately left out.

1. Twenty assert/*-array packages place their entire implementation — a single arrayfun( pred ) call — directly in lib/index.js with no lib/main.js, and consequently carry no function-level JSDoc on the export. Six structural twins in the same directory do the opposite; is-truthy-array and is-falsy-array are byte-for-byte analogous apart from this. Namespace-wide, lib/main.js is present in 92.8% of packages, but among packages whose implementation is a bare factory call the count runs 20 without to 6 with, so the split is not settled for this shape, and docs/contributing/packages.md is permissive ("typically", "most commonly"). Should these twenty be normalized, and in which direction?
2. Nine packages disagree with themselves on a parameter name between lib/main.js and docs/types/index.d.ts, against a 97.1% intra-package invariant: is-struct and is-struct-constructor-like (value vs v), is-prng-like (v vs value), is-binary-string (str vs value), and is-alphagram, is-alphanumeric, is-ascii, is-digit-string, is-hex-string (x vs value). docs/repl.txt is a third naming layer that disagrees again in most of these, so no single rename reconciles all three, and index.d.ts is published TypeScript surface. Left alone pending a decision on the target name.
3. is-mobile/lib/browser.js and is-touch-device/lib/browser.js export functions, while their Node entry points export booleans and every sibling browser.js (is-browser, is-docker, is-electron, is-electron-main, is-electron-renderer, is-node) exports a plain true/false. Since package.json browser substitutes that file for main, those two packages change export shape between builds. This looks like a defect rather than a convention, but fixing it would change observable behavior, so it is out of scope here.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

Namespace survey. 348 packages in assert, all hand-maintained (no wholly generated members). Features examined: package file tree, package.json key sets, scripts/stdlib keys, manifest.json keys, README heading set and order, test/benchmark/example filenames, public signature, return kind, validation prologue, error construction, JSDoc shape, and internal dependencies.

Features with a clear ≥75% pattern: file tree, package.json top-level keys (100% on all eighteen), README heading set and order (100% on Usage/Examples), test/test.js presence, return kind (100% boolean), @example presence (100%), @param {*} for a single value argument (220/220), and format for thrown validation errors (12/12 packages that throw). Features excluded for having no clear pattern: README See Also (69.3%, and generator-populated), Notes (35.6%), CLI (23.3%), public signature (( value ) at 45.5% — a plurality only), and internal dependencies (highest single dependency at 11.2%). scripts is {} in all 348.

Validation. Structural features were extracted from the filesystem, semantic features from source. Three agents then audited the dismissals rather than the corrections, which is where a survey like this goes wrong, and each of their findings was re-verified against the tree before being acted on. Two discriminations mattered:

• Benchmark absence had been waved off as "environment detection is not worth benchmarking". True for the thirteen assert packages exporting a precomputed boolean, false for is-node-repl, which exports a function. Export shape predicts benchmark presence almost perfectly repository-wide — 4813 of 5246 function-exporting packages (91.7%) ship one, against 0 of 354 packages exporting a constant.
• @param {string} on a value argument looked like three outliers. Only one is: has-utf16-surrogate-pair-at and is-anagram throw on non-string input, verified at runtime, so their type is right.

Also deliberately excluded: three packages whose @returns ends in a period against a 99.1% norm (is-complex-like, is-even, is-odd) — an inconsistency, but not a defect, and not worth churn; the twenty-four packages using the terser "boolean result" phrasing, which is the norm for the ( v1, v2 ) comparison cluster and so has no unambiguous direction; the fifteen constant-exporting packages with no benchmark; the twenty-nine packages shipping benchmark.length.js, which have real length-parameterized coverage; is-absolute-path and is-relative-path, whose posix.js/win32.js branch files are required directly by their tests, so promoting either to main.js would be a breaking rename; and the napi and tools sub-namespace containers.

Local validation. All four modified files pass node --check. The directories lint that lint_package_json_files runs was reproduced locally and confirmed idempotent for all four packages. The benchmark file differs from has-symbol-support/benchmark/benchmark.js only in the copyright year, one require's variable name, and the call site. @stdlib/bench and ESLint could not be run — third-party dependencies are absent in the authoring environment, and the pre-existing has-symbol-support benchmark fails identically — so the harness was not executed. CI is the gate for those.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

• Read, understood, and followed the contributing guidelines.

AI Assistance

When authoring the changes proposed in this PR, did you use any kind of AI assistance?

• Yes
• No

If you answered "yes" above, how did you use AI assistance?

• Code generation (e.g., when writing an implementation or fixing a bug)
• Test/benchmark generation
• Documentation (including examples)
• Research and understanding

Disclosure

If you answered "yes" to using AI assistance, please provide a short disclosure indicating how you used AI assistance. This helps reviewers determine how much scrutiny to apply when reviewing your contribution. Example disclosures: "This PR was written primarily by Claude Code." or "I consulted ChatGPT to understand the codebase, but the proposed changes were fully authored manually by myself.".

This PR was written by Claude Code as part of an automated survey of convention consistency across the assert namespace. The survey, the four changes, and this description were all produced by Claude Code. The benchmark harness and ESLint could not be executed in the authoring environment, so reviewers should rely on CI for those. The three questions above are open and have not been acted on.

---

@stdlib-js/reviewers

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
assert/is-leap-year	$\\color{green}131/131$ $\\color{green}+100.00\\%$	$\\color{green}12/12$ $\\color{green}+100.00\\%$	$\\color{green}1/1$ $\\color{green}+100.00\\%$	$\\color{green}131/131$ $\\color{green}+100.00\\%$
assert/is-ndarray-like-with-data-type	$\\color{green}99/99$ $\\color{green}+100.00\\%$	$\\color{green}4/4$ $\\color{green}+100.00\\%$	$\\color{green}1/1$ $\\color{green}+100.00\\%$	$\\color{green}99/99$ $\\color{green}+100.00\\%$
assert/is-node-repl	$\\color{green}225/225$ $\\color{green}+0.00\\%$	$\\color{green}15/15$ $\\color{green}+0.00\\%$	$\\color{green}3/3$ $\\color{green}+0.00\\%$	$\\color{green}225/225$ $\\color{green}+0.00\\%$
assert/is-well-formed-string	$\\color{red}334/340$ $\\color{green}+98.24\\%$	$\\color{red}25/27$ $\\color{green}+92.59\\%$	$\\color{green}4/4$ $\\color{green}+100.00\\%$	$\\color{red}334/340$ $\\color{green}+98.24\\%$

The above coverage report was generated for the changes in this PR.