refactor: normalize error messages and descriptions#12214
Merged
Conversation
…/namespace-aliases` Replaces "Last argument" with "Callback argument" in the `TypeError` thrown by `lib/async.js` when the callback parameter is not a function, and updates the matching `@throws` JSDoc tag. The "Callback argument" phrasing is used by 7 of the 8 sibling `@stdlib/_tools/lint/*` packages with a callback validation (87.5% conformance); `namespace-aliases` was the only outlier.
…s/lint/pkg-json-names`
Adds the missing `@throws {TypeError} options argument must be an
object` line to the `lib/async.js` JSDoc; the throw is already present
in `lib/validate.js` but was undocumented at the public entry. All 6
sibling `@stdlib/_tools/lint/*` packages with `options` validation
document this throw (100% conformance among comparable siblings).
Prepends a leading blank line to `docs/usage.txt` so the CLI `--help`
banner matches the vertical spacing produced by the other 8 sibling
packages, all of which start their `docs/usage.txt` with `\n`.
kgryte
changed the title
@stdlib/_tools/lint
kgryte
approved these changes
May 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This pull request:
@stdlib/_tools/lint/*namespace to the conventions used by the rest of the namespace, found via a cross-package drift sweep. No observable behavior changes — error type, JSDoc tag set, and CLI output are otherwise unchanged.Namespace summary
@stdlib/_tools/lint(9 non-autogenerated packages)package.jsonshape, README section list,lib/async.js/lib/main.jsJSDoc shape, error-construction style, validation prologue,docs/usage.txtformatting.@throws {TypeError} options argument must be an objectin the JSDoc of packages that accept an options object; leading newline indocs/usage.txt.osfield inpackage.json(2/9 vs 7/9 split, intentional vs accidental unclear); thecbvsclbkcallback parameter name; presence oflib/sync.js/lib/async.js/lib/validate.js(genuine API-shape differences across packages).@stdlib/_tools/lint/namespace-aliasesReplaces
"Last argument must be a function."with"Callback argument must be a function."in theTypeErrorthrown bylib/async.js, and updates the matching@throwsJSDoc tag. All 7 other sibling packages with a callback-arity validation use the"Callback argument"phrasing (87.5% conformance, 7/8 of comparable siblings); the function signature islint( options, clbk )withclbkunambiguously the callback, so the"Last argument"wording is a copy-paste outlier with no semantic justification.@stdlib/_tools/lint/pkg-json-namesTwo corrections in this package:
* @throws {TypeError} options argument must be an objectline to the JSDoc forlib/async.js. The throw is already implemented inlib/validate.jsbut undocumented at the public entry. All 6 sibling packages that accept anoptionsobject document this throw (100% conformance).docs/usage.txt. The file is read at runtime into the CLI's--helpoutput, and 8 of 8 sibling packages start theirdocs/usage.txtwith\n;pkg-json-nameswas the only one starting on theUsage:line, which produced subtly different vertical spacing in--help.Validation
package.jsonkeys, README section list, anddocs/usage.txtfirst byte across all 9 namespace members.confirmed-driftrather than an intentional deviation. Cross-reference verified that tests in both packages assert only oninstanceof TypeError, never on message text, and that the CLI'stest.cli.jsreadsdocs/usage.txtsymmetrically against the produced--helpoutput.osfield divergence (behavior-affecting, unclear majority), thecb/clbknaming difference (no 75% majority), and the empty<section class="notes">inpkg-json/repl-txtREADMEs (requires authored content, not mechanical).Related Issues
No.
Questions
No.
Other
Each outlier package has its own commit so the audit trail is per-package. Conformance percentages for each item are quoted in the respective commit body.
Checklist
AI Assistance
If you answered "yes" above, how did you use AI assistance?
Disclosure
This PR was produced by a cross-package API drift sweep run by Claude Code. The drift signals (majority error phrasing, missing JSDoc tag, missing leading newline in
docs/usage.txt) were extracted automatically across the 9 packages in@stdlib/_tools/lint, then validated by three review passes before any file was modified. All edits are mechanical text substitutions in two packages; no behavior, signatures, or test expectations changed.@stdlib-js/reviewers
Generated by Claude Code