build: add `format-args` ESLint rule by Planeshifter · Pull Request #14518 · stdlib-js/stdlib

Planeshifter · 2026-08-22T05:41:47Z

Resolves stdlib-js/metr-issue-tracker#660.

Description

What is the purpose of this pull request?

This pull request:

adds a custom ESLint rule (stdlib/format-args) which verifies that calls to the format function exported by @stdlib/string/format are provided a number of arguments matching the number of placeholders in the format string.
registers the rule in the rules namespace and enables the rule in the ESLint configuration.

Implementation notes:

The rule uses @stdlib/string/base/format-tokenize to tokenize the format string and count placeholders. Escaped percent signs (%%) do not consume arguments, and dynamic widths and precisions (e.g., %*d and %.*f) each consume an additional argument.
Rather than blanket matching any identifier named format, the rule resolves each call expression's callee symbol via scope analysis (walking parent scopes and inspecting the nearest binding), thus guarding against shadowed symbols and unrelated symbols sharing the same name. Only symbols bound via require( '@stdlib/string/format' ) are checked.
The rule skips calls via #.call and #.apply, calls in which the format string is not a string literal, calls containing spread elements, and format strings containing positional placeholders (e.g., %1$s), as the latter may consume arguments out-of-order and/or reuse arguments.

Running the rule over all 13,722 files in the repository containing a string/format require statement surfaced two genuine bugs and zero false positives. Fixes for those bugs were submitted separately in #14517.

Related Issues

Does this pull request have any related issues?

This pull request has the following related issues:

fix: add missing arguments to format calls #14517 (fixes for the two violations surfaced by this rule)

Questions

Any questions for reviewers of this pull request?

No.

Other

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

A shared scope-resolution utility (as floated in the issue) was not created, as the nearest-binding scope walk is ~25 lines and currently has only two potential call sites (this rule and no-builtin-big-int); extracting a common _tools/eslint/utils package can be revisited if a third rule needs it.

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 under my direction and instructions, following existing rule packages as templates.

@stdlib-js/reviewers

Adds a custom ESLint rule which verifies that calls to the format function exported by `@stdlib/string/format` are provided a number of arguments matching the number of placeholders in the format string. The rule resolves the callee symbol via scope analysis in order to guard against shadowing and unrelated symbols sharing the same name, and skips calls via `#.call` and `#.apply`, calls in which the format string is not a string literal, calls containing spread elements, and format strings containing positional placeholders. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown_pkg_readmes status: passed - task: lint_markdown_docs status: na - task: lint_markdown status: na - task: lint_package_json status: passed - task: lint_repl_help status: na - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: passed - task: lint_javascript_tests status: passed - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: passed - task: lint_typescript_tests status: na - task: lint_license_headers status: passed ---

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown_pkg_readmes status: passed - task: lint_markdown_docs status: na - task: lint_markdown status: na - task: lint_package_json status: passed - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: passed - task: lint_typescript_tests status: na - task: lint_license_headers status: passed ---

Planeshifter · 2026-08-22T06:20:16Z

@@ -1 +1 @@
 /* eslint-disable stdlib/jsdoc-doctest-marker, stdlib/jsdoc-example-require-spacing, stdlib/jsdoc-no-tabs */


Automatically removed by our ESLint autofix because these are not needed anymore here.

PR-URL: #14517 Reviewed-by: Athan Reines <kgryte@gmail.com> Ref: #14518

Signed-off-by: Athan <kgryte@gmail.com>

Co-authored-by: Athan <kgryte@gmail.com> Signed-off-by: Athan <kgryte@gmail.com>

kgryte

LGTM

Planeshifter force-pushed the philipp/format-args-lint-rule branch from 2a1ba12 to 730cfb5 Compare August 22, 2026 05:43

Planeshifter mentioned this pull request Aug 22, 2026

fix: add missing arguments to format calls #14517

Merged

3 of 7 tasks

Planeshifter changed the title ~~feat: add format-args ESLint rule~~ build: add format-args ESLint rule Aug 22, 2026

Planeshifter marked this pull request as ready for review August 22, 2026 06:01

Planeshifter requested a review from a team August 22, 2026 06:01

stdlib-bot added the Needs Review A pull request which needs code review. label Aug 22, 2026

Planeshifter mentioned this pull request Aug 22, 2026

feat: add no-unnecessary-format ESLint rule #14519

Merged

6 of 7 tasks

Planeshifter commented Aug 22, 2026

View reviewed changes

kgryte pushed a commit that referenced this pull request Aug 22, 2026

fix: add missing arguments to format calls

668ccdd

PR-URL: #14517 Reviewed-by: Athan Reines <kgryte@gmail.com> Ref: #14518

refactor: use assertion utility

0aac681

Signed-off-by: Athan <kgryte@gmail.com>

kgryte reviewed Aug 22, 2026

View reviewed changes

Comment thread lib/node_modules/@stdlib/_tools/eslint/rules/format-args/test/fixtures/invalid.js Outdated

kgryte reviewed Aug 22, 2026

View reviewed changes

Comment thread lib/node_modules/@stdlib/_tools/eslint/rules/format-args/test/fixtures/unvalidated.js Outdated

kgryte reviewed Aug 22, 2026

View reviewed changes

Comment thread lib/node_modules/@stdlib/_tools/eslint/rules/format-args/test/fixtures/valid.js Outdated

Apply suggestions from code review

9462818

Co-authored-by: Athan <kgryte@gmail.com> Signed-off-by: Athan <kgryte@gmail.com>

kgryte approved these changes Aug 22, 2026

View reviewed changes

kgryte merged commit f6bb7cb into develop Aug 22, 2026
10 checks passed

kgryte deleted the philipp/format-args-lint-rule branch August 22, 2026 08:15

stdlib-bot removed the Needs Review A pull request which needs code review. label Aug 22, 2026

Planeshifter added the METR Pull request associated with the METR project. label Aug 26, 2026

Navigation Menu

Repository navigation

build: add `format-args` ESLint rule - #14518

build: add `format-args` ESLint rule#14518
kgryte merged 4 commits into
developfrom
philipp/format-args-lint-rule

Planeshifter commented Aug 22, 2026 •

edited

Loading

Uh oh!

Planeshifter Aug 22, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kgryte left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		@@ -1 +1 @@
		/* eslint-disable stdlib/jsdoc-doctest-marker, stdlib/jsdoc-example-require-spacing, stdlib/jsdoc-no-tabs */

Conversation

Planeshifter commented Aug 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related Issues

Questions

Other

Checklist

AI Assistance

Disclosure

Uh oh!

Planeshifter Aug 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kgryte left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Planeshifter commented Aug 22, 2026 •

edited

Loading