Skip to content

feat: add jsdoc-example-eslint ESLint rule - #11101

Open
Planeshifter wants to merge 5 commits into
developfrom
philipp/jsdoc-example-eslint
Open

feat: add jsdoc-example-eslint ESLint rule#11101
Planeshifter wants to merge 5 commits into
developfrom
philipp/jsdoc-example-eslint

Conversation

@Planeshifter

@Planeshifter Planeshifter commented Mar 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

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

Description

What is the purpose of this pull request?

This pull request:

  • Adds a new custom ESLint rule jsdoc-example-eslint that extracts JavaScript code from JSDoc @example blocks and lints it using ESLint's synchronous Linter API
  • Configures the rule in eslint.config.js using the shared standalone example rules, keeping JSDoc example linting in sync with example file linting
  • Uses ESLint 9 flat-config plugin registration in the executable and README examples

Related Issues

Does this pull request have any related issues?

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.

The rule is a pure mechanism: it accepts a rules object and lints example code with those rules, reporting violations mapped back to the correct source file lines. It has no built-in opinions about which rules to apply.

The rule is configured in eslint.config.js after the base rule modules load, avoiding a circular dependency with stdlib.js. Standalone examples and JSDoc snippets share the same example overrides.

The shared example rules are filtered to exclude plugin rules (which the internal Linter instance doesn't have registered) and rules incompatible with code snippets (no-undef, no-unused-vars, strict, no-var, eol-last, indent, no-restricted-syntax).

Validation after rebasing: unit tests, executable and README examples, flat-config integration (shared core rules, exclusions, severity, and source-line reporting), JavaScript and Markdown lint, package validation, license headers, EditorConfig, and git diff --check pass.

Checklist

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

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

This PR was written primarily by Claude Code following my instructions. Codex assisted with rebasing and ESLint 9 compatibility updates.

@stdlib-js/reviewers

@socket-security

socket-security Bot commented Mar 23, 2026 •
edited
Loading

Copy link
Copy Markdown

No dependency changes detected. Learn more about Socket for GitHub.

👍 No dependency changes detected in pull request

@Planeshifter
Planeshifter force-pushed the philipp/jsdoc-example-eslint branch 2 times, most recently from 8fce0dc to 33e0f6e Compare March 23, 2026 05:46
@Planeshifter Planeshifter added Feature Issue or pull request for adding a new feature. METR Pull request associated with the METR project. labels Mar 23, 2026
@Planeshifter
Planeshifter force-pushed the philipp/jsdoc-example-eslint branch from 33e0f6e to 9dbe8eb Compare March 23, 2026 06:03
@github-actions github-actions Bot mentioned this pull request Mar 23, 2026
Closed
@Planeshifter
Planeshifter marked this pull request as ready for review April 27, 2026 04:35
@Planeshifter
Planeshifter requested a review from a team April 27, 2026 04:35
@stdlib-bot stdlib-bot added the Needs Review A pull request which needs code review. label Apr 27, 2026
@Planeshifter
Planeshifter requested a review from kgryte April 27, 2026 04:35
kgryte
kgryte reviewed Apr 27, 2026
View reviewed changes
Comment thread tools/make/lib/init/eslint.mk Resolved
kgryte
kgryte reviewed Apr 27, 2026
View reviewed changes
Comment thread etc/eslint/.eslintrc.overrides.js Outdated

@kgryte kgryte Apr 27, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm at a loss for explaining why the overrides file is being modified in this PR.

@kgryte kgryte Apr 27, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe that the actual approach which should be taken is to 1) create an .eslintrc.jsdoc.js file which uses the .eslintrc.examples.js file has the source of the defaults and 2) enables the rule in the stdlib.js file by loading in the file created in step (1).

As it is, this PR seems confused and is just creating a configuration mess.

@Planeshifter Planeshifter Apr 28, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's workaround to avoid a circular dependency as was detailed in the PR description:

The rule is configured in .eslintrc.overrides.js (rather than stdlib.js) to avoid a circular dependency: stdlib.js → .eslintrc.examples.js → .eslintrc.js → rules/index.js → stdlib.js. The overrides file loads after the base config resolves, so it can safely require the examples config.

Per Claude,

What actually happens at runtime under that cycle: when stdlib.js is being evaluated as part of resolving .eslintrc.js,
requiring .eslintrc.jsdoc.js reaches back to .eslintrc.js mid-evaluation. Node returns the partial module.exports (empty at
that point). .eslintrc.examples.js does copy(defaults) against {}, sets a handful of its own rules, returns a near-empty
config. .eslintrc.jsdoc.js filters that near-empty rules map and the jsdoc-example-eslint rule ends up with effectively no
rules to apply. Silent breakage — the linter loads, but the JSDoc snippet rule does nothing.

I ran into this problem during development of this rule. To address your desire, Claude suggests

split config into .eslintrc.jsdoc.js, but keep wiring in .eslintrc.overrides.js (one-liner:
eslint.rules['stdlib/jsdoc-example-eslint'] = ['warn', require('./.eslintrc.jsdoc.js')];). Cycle stays broken because the
overrides file resolves AFTER the base. Addresses his "config mess" complaint cleanly: the heavy lifting lives in a
dedicated, named file consistent with .eslintrc.examples.js/.eslintrc.tests.js/.eslintrc.benchmarks.js; the overrides file
just hooks it up.

Thoughts?

kgryte
kgryte reviewed Apr 27, 2026
View reviewed changes
Comment thread etc/eslint/.eslintrc.overrides.js Outdated
for ( i = 0; i < keys.length; i++ ) {
key = keys[ i ];

// Skip plugin rules (e.g., "stdlib/foo", "node/bar") since the Linter instance does not have them registered:

@kgryte kgryte Apr 27, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand this comment.

kgryte
kgryte reviewed Apr 27, 2026
View reviewed changes
Comment thread etc/eslint/.eslintrc.overrides.js Outdated
* @private
* @type {Array}
*/
var JSDOC_SNIPPET_EXCLUDE = [

@kgryte kgryte Apr 27, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Refer to other files such as .eslintrc.examples for how rules are overridden. In short, be consistent with what we already have.

kgryte
kgryte requested changes Apr 27, 2026
View reviewed changes

@kgryte kgryte left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left initial comments.

@kgryte kgryte added Tools Issue or pull request related to project tooling. Needs Changes Pull request which needs changes before being merged. and removed Needs Review A pull request which needs code review. labels Apr 27, 2026
@Planeshifter
Planeshifter force-pushed the philipp/jsdoc-example-eslint branch from f807776 to 6b854ee Compare April 28, 2026 05:11
@kgryte

kgryte commented Aug 19, 2026

Copy link
Copy Markdown
Member

cc @Planeshifter Mind updating this PR to resolve the CI failures?

@kgryte kgryte added Needs Review A pull request which needs code review. and removed Needs Changes Pull request which needs changes before being merged. labels Aug 26, 2026
@kgryte
kgryte self-requested a review October 28, 2026 00:29
@Planeshifter
feat: add jsdoc-example-eslint ESLint rule
56b5674 
Add a new custom ESLint rule that extracts JavaScript code from
JSDoc `@example` blocks and lints it using ESLint's synchronous
`Linter` API. The rule is a pure mechanism: it accepts a `rules`
object and lints example code with those rules, reporting violations
mapped back to the correct source file lines.

The rule is configured in `.eslintrc.overrides.js`, where the
examples ESLint config is loaded (avoiding a circular dependency
with `stdlib.js`), filtered to exclude plugin rules and rules
incompatible with code snippets, and passed to the rule.

---
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
    status: passed
  - 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
---
@Planeshifter
style: align jsdoc-example-eslint package with peer rule conventions
04437aa 
Rename the local require alias in `lib/index.js` from `rule` to `main`
to match the convention used across all peer ESLint rule packages
(e.g., `jsdoc-empty-line-before-example`, `jsdoc-doctest-decimal-point`),
and replace the dangling `var config` block in the `@example` JSDoc with
a `console.log( main );` per the peer pattern.

Drop the spurious `// VARIABLES //` section marker from the `valid.js`
test fixture; peer fixtures and this package's own `invalid.js` do not
use section markers in fixture files.

---
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
    status: na
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: na
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: na
  - 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
---
@Planeshifter
style: address review feedback on jsdoc-example-eslint
4696835 
Inline `var test = {…}` for the first test in `invalid.js` / `valid.js`
and drop the upfront `var test;` declaration. Move the `var code` /
`var result` declarations to the top of `examples/index.js` and the
README example, removing the empty up-front declarations. Rename the
inaccurate `// Example with if statement and curly braces:` test
comment in `valid.js` to reflect what the JSDoc actually exercises.

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: skipped
  - task: lint_editorconfig
    status: skipped
  - task: lint_markdown
    status: skipped
  - task: lint_package_json
    status: skipped
  - task: lint_repl_help
    status: skipped
  - task: lint_javascript_src
    status: skipped
  - task: lint_javascript_cli
    status: skipped
  - task: lint_javascript_examples
    status: skipped
  - task: lint_javascript_tests
    status: skipped
  - task: lint_javascript_benchmarks
    status: skipped
  - 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: skipped
  - task: lint_typescript_tests
    status: skipped
  - task: lint_license_headers
    status: skipped
---
@Planeshifter
docs: replace removed valid-jsdoc rule in README lint directives
b279681 
The `valid-jsdoc` core rule was removed from the ESLint configuration in
favor of `eslint-plugin-jsdoc` rules, so disabling it no longer suppresses
`jsdoc/require-param` and `jsdoc/require-returns` for the README code
blocks illustrating the rule.

---
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: na
  - 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
build: align JSDoc example linting with ESLint 9
3476643
@Planeshifter
Planeshifter force-pushed the philipp/jsdoc-example-eslint branch from 8cc8af9 to 3476643 Compare October 29, 2026 14:21

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@kgryte kgryte Awaiting requested review from kgryte

Requested changes must be addressed to merge this pull request.

Assignees

No one assigned

Labels

Feature Issue or pull request for adding a new feature. METR Pull request associated with the METR project. Needs Review A pull request which needs code review. Tools Issue or pull request related to project tooling.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[RFC]: Setup ESLint linting in JSDoc examples

3 participants

@Planeshifter @kgryte @stdlib-bot