Skip to content

build: add tsdoc-doctest ESLint rule #8039

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 5 commits into
base: develop
Choose a base branch
from
Open

build: add tsdoc-doctest ESLint rule #8039

wants to merge 5 commits into from
+1,653 −1

Conversation

Planeshifter
Copy link
Member

Description

What is the purpose of this pull request?

This pull request:

  • adds tsdoc-doctest ESLint rule for for linting return annotations in TSDoc example code inside of TypeScript declaration files.

Related Issues

Does this pull request have any related issues?

This pull request:

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.

No.

Checklist

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

@stdlib-js/reviewers

@Planeshifter
build: add tsdoc-doctest ESLint rule for linting return annotations…
d4211dd 
… in TSDoc examples

---
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: 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: na
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---
@Planeshifter
build: minor refactoring
f723627 
---
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: 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: na
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---
@Planeshifter Planeshifter changed the title [WIP] build: add tsdoc-doctest ESLint rule build: add tsdoc-doctest ESLint rule Sep 16, 2025
@Planeshifter Planeshifter force-pushed the philipp/add-typescript-doctest-linting branch from 15a3eab to f723627 Compare September 16, 2025 16:47
@Planeshifter
refactor: clean-up and handle interface case
9dd2b66 
---
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: 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: na
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---
@Planeshifter Planeshifter marked this pull request as ready for review September 17, 2025 06:39
@stdlib-bot stdlib-bot added the Needs Review A pull request which needs code review. label Sep 17, 2025
@Planeshifter Planeshifter requested a review from kgryte September 17, 2025 06:39
@kgryte kgryte added the Tools Issue or pull request related to project tooling. label Sep 17, 2025
kgryte
kgryte reviewed Sep 17, 2025
View reviewed changes
@kgryte
docs: update comment to avoid non-conventional capitalization
5f3400b 
Signed-off-by: Athan <kgryte@gmail.com>
kgryte
kgryte reviewed Sep 17, 2025
View reviewed changes
kgryte
kgryte reviewed Sep 17, 2025
View reviewed changes
lib/node_modules/@stdlib/_tools/eslint/rules/tsdoc-doctest/README.md
- The corresponding JavaScript package must be loadable via `require('@stdlib/<package>')`
- The rule skips validation if the package cannot be loaded.
- Examples are executed in a sandboxed VM context with limited globals.
- The rule validates assignment-form examples (e.g., `var x = fn(...);` followed by an annotation). It does not validate console output or expression-only forms using `// =>`.
Copy link
Member

Choose a reason for hiding this comment

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

Why this limitation?

kgryte
kgryte reviewed Sep 17, 2025
View reviewed changes
lib/node_modules/@stdlib/_tools/eslint/rules/tsdoc-doctest/lib/add_package_to_scope.js
var funcMatch;

if ( typeof pkg === 'function' ) {
// Try to match declare function pattern (handles generics with <):
Copy link
Member

Choose a reason for hiding this comment

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

Similar to L60, it would be nice to include an example in each of the comments (L50, L54, etc) which demonstrate what pattern we are attempting to match.

kgryte
kgryte reviewed Sep 17, 2025
View reviewed changes
lib/node_modules/@stdlib/_tools/eslint/rules/tsdoc-doctest/lib/main.js
var key;

escapedValue = escapeRegex( value );
key = [ annotationType, escapedValue ].join( '::' );
Copy link
Member

Choose a reason for hiding this comment

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

Is it really necessary to create a temporary array here?

kgryte
kgryte reviewed Sep 17, 2025
View reviewed changes
lib/node_modules/@stdlib/_tools/eslint/rules/tsdoc-doctest/lib/main.js
*
* @private
* @param {Object} scope - VM scope
* @param {any} expected - expected value to search for
Copy link
Member

Choose a reason for hiding this comment

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

any is not valid.

kgryte
kgryte reviewed Sep 17, 2025
View reviewed changes
lib/node_modules/@stdlib/_tools/eslint/rules/tsdoc-doctest/lib/main.js
* @private
* @param {string} filepath - TypeScript declaration file path
* @param {string} implementationPath - relative path to implementation
* @returns {string|null} resolved implementation path or null if not found
Copy link
Member

Choose a reason for hiding this comment

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

Missing parens.

kgryte
kgryte reviewed Sep 17, 2025
View reviewed changes
lib/node_modules/@stdlib/_tools/eslint/rules/tsdoc-doctest/lib/main.js

last = 0;
RE_ANNOTATION.lastIndex = 0;
try {
Copy link
Member

Choose a reason for hiding this comment

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

I am not sure why we are enclosing the entirety of the code logic in a try block. This is obviously not best practice. I see that the same thing was done in jsdoc-doctest; that should also be cleaned up. Otherwise, we are swallowing programmer errors.

kgryte
kgryte reviewed Sep 17, 2025
View reviewed changes
lib/node_modules/@stdlib/_tools/eslint/rules/tsdoc-doctest/lib/main.js
options = context.options[ 0 ] || {};

// Only process TypeScript declaration files:
if ( !filename.endsWith( '.d.ts' ) ) {
Copy link
Member

Choose a reason for hiding this comment

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

I wonder if we should rename this rule to make this more explicit that it won't work on TS source files. E.g., tsdoc-declarations-doctest, or similar.

kgryte
kgryte reviewed Sep 17, 2025
View reviewed changes
lib/node_modules/@stdlib/_tools/eslint/rules/tsdoc-doctest/lib/main.js
lineCountCache = {};

// Resolve implementation path relative to TypeScript declaration file path:
implementationPath = options.implementationPath || '../../lib';
Copy link
Member

Choose a reason for hiding this comment

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

Remind me: why don't we want to resolve the nearest package.json and the associated main entry point?

kgryte
kgryte requested changes Sep 17, 2025
View reviewed changes
Copy link
Member

@kgryte kgryte left a comment

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 Needs Changes Pull request which needs changes before being merged. TypeScript Issue involves or relates to TypeScript. and removed Needs Review A pull request which needs code review. labels Sep 17, 2025
@Planeshifter @kgryte
docs: add missing period
e79a1ac 
Co-authored-by: Athan <kgryte@gmail.com>
Signed-off-by: Philipp Burckhardt <pburckhardt@outlook.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@kgryte kgryte kgryte requested changes

Requested changes must be addressed to merge this pull request.

Assignees
No one assigned
Labels
Needs Changes Pull request which needs changes before being merged. Tools Issue or pull request related to project tooling. TypeScript Issue involves or relates to TypeScript.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

[RFC]: add support for doctesting in TypeScript declaration files
3 participants
@Planeshifter @kgryte @stdlib-bot