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 18 commits into
base: develop
Choose a base branch
from
Open

build: add tsdoc-doctest ESLint rule #8039

wants to merge 18 commits into from
+2,517 −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 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 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
kgryte reviewed Sep 17, 2025
View reviewed changes
kgryte
kgryte reviewed Sep 17, 2025
View reviewed changes
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-declarations-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.

Copy link
Member

Choose a reason for hiding this comment

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

@Planeshifter You marked this as resolved, but didn't make any changes.

@kgryte kgryte removed the Needs Changes Pull request which needs changes before being merged. label Sep 29, 2025
kgryte
kgryte reviewed Sep 29, 2025
View reviewed changes
@kgryte
docs: fix comment
86ac0f0 
Signed-off-by: Athan <kgryte@gmail.com>
@kgryte
docs: update description
1d346e5 
Signed-off-by: Athan <kgryte@gmail.com>
@kgryte
docs: update description
eb49b5f 
Signed-off-by: Athan <kgryte@gmail.com>
@kgryte
docs: fix notes placement and update description
f965f20 
Signed-off-by: Athan <kgryte@gmail.com>
@kgryte
docs: update example
911504b 
Signed-off-by: Athan <kgryte@gmail.com>
@kgryte
docs: update example
d86dcff 
Signed-off-by: Athan <kgryte@gmail.com>
@kgryte
docs: fix comment style
1a1fc84 
Signed-off-by: Athan <kgryte@gmail.com>
@kgryte
style: don't break expressions
adbc303 
Signed-off-by: Athan <kgryte@gmail.com>
kgryte
kgryte reviewed Sep 29, 2025
View reviewed changes
...e_modules/@stdlib/_tools/eslint/rules/tsdoc-declarations-doctest/lib/add_package_to_scope.js
if ( pkgType === 'object' && pkg !== null ) {
namespaceMatch = sourceText.match( RE_DECLARE_VAR_INTERFACE );
if ( namespaceMatch ) {
scope[ namespaceMatch[1] ] = pkg;
Copy link
Member

Choose a reason for hiding this comment

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

@Planeshifter You fall-through here. Is that intended?

Copy link
Member

Choose a reason for hiding this comment

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

If so, it would be good to document that the fall-through is intended.

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

var vm = require( 'vm' );
var resolve = require( 'path' ).resolve;
var readFileSync = require( 'fs' ).readFileSync; // eslint-disable-line node/no-sync
Copy link
Member

Choose a reason for hiding this comment

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

@Planeshifter We should be using @stdlib/fs/read-file.sync.

kgryte
kgryte reviewed Sep 29, 2025
View reviewed changes
lib/node_modules/@stdlib/_tools/eslint/rules/tsdoc-declarations-doctest/lib/main.js
if ( lineCountCache[ str ] ) {
return lineCountCache[ str ];
}
lines = str.split( reEOL() );
Copy link
Member

Choose a reason for hiding this comment

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

@Planeshifter You don't need to create a new EOL regexp here. Use .REGEXP from the respective package.

kgryte
kgryte reviewed Sep 29, 2025
View reviewed changes
lib/node_modules/@stdlib/_tools/eslint/rules/tsdoc-declarations-doctest/lib/main.js
function countLines( str ) {
var lines;

// Use cached result if available
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
// Use cached result if available

What if the line count in the cache is 0?

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

// Read and parse package.json:
try {
pkgJSON = JSON.parse( readFileSync( pkgPath, 'utf8' ) );
Copy link
Member

Choose a reason for hiding this comment

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

@Planeshifter Use @stdlib/utils/parse-json. Then handle with

json = parseJSON(...);
if ( json instanceof Error ) {
    debug( .... );
    return null;
}

But also, more generally here, you can use @stdlib/fs/read-json which combines both reading and parsing.

kgryte
kgryte reviewed Sep 29, 2025
View reviewed changes
lib/node_modules/@stdlib/_tools/eslint/rules/tsdoc-declarations-doctest/lib/main.js
Comment on lines +171 to +173
mainPath = pkgJSON.main || './lib';
pkgDir = dirname( pkgPath );
return resolve( pkgDir, mainPath );
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
mainPath = pkgJSON.main || './lib';
pkgDir = dirname( pkgPath );
return resolve( pkgDir, mainPath );
return resolve( dirname( pkgPath ), pkgJSON.main || './lib' );

The intermediate variables are not particularly useful here.

Copy link
Member

Choose a reason for hiding this comment

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

What if pkgJSON.main is the empty string? In that case, main would default to index.js. Here, you default to ./lib which I don't think would be correct.

@kgryte
refactor: avoid unnecessary intermediate variable
75bc34d 
Signed-off-by: Athan <kgryte@gmail.com>
@kgryte
docs: update description
7a94b5a 
Signed-off-by: Athan <kgryte@gmail.com>
@kgryte
docs: update description
3fe88ba 
Signed-off-by: Athan <kgryte@gmail.com>
kgryte
kgryte requested changes Sep 29, 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.

Only a few comments remain wrt the main implementation.

@kgryte kgryte added Needs Changes Pull request which needs changes before being merged. and removed Needs Review A pull request which needs code review. labels Sep 29, 2025
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