Skip to content

fix: drop eslint-plugin-tsdoc from the TypeScript lint preset - #130

Merged
chaitanyapotti merged 8 commits into
mainfrom
fix/drop-eslint-plugin-tsdoc
Nov 12, 2026
Merged

chaitanyapotti merged 8 commits into
mainfrom
fix/drop-eslint-plugin-tsdoc

Conversation

@hieu-w

@hieu-w hieu-w commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Motivation and Context

eslint-plugin-tsdoc depends on @typescript-eslint/utils, which forces TypeScript 5 into the install tree and cannot load with TypeScript 7. That is the same class of problem as the @typescript-eslint rules already replaced by the local torus plugin.

Jira Link

N/A

Description

Remove eslint-plugin-tsdoc from @toruslabs/oxlint-config-typescript and depend on @microsoft/tsdoc instead. The tsdoc/syntax rule stays. A local Oxlint JS plugin, tsdoc-plugin.mjs, wraps @microsoft/tsdoc and replaces the ESLint plugin. vp pack now ships that plugin with the preset. The lockfile drops the @typescript-eslint subtree that the old plugin pulled in.

How has this been tested?

  • vp test packages/oxlint-config-typescript/index.test.ts (5 tests passed), including the existing tsdoc(syntax) diagnostic check

Screenshots (if appropriate)

N/A

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

  • My code follows the code style of this project. (run lint)
  • My change requires a change to the documentation.
  • I have updated the documentation accordingly.
  • I have added tests to cover my changes.
  • All new and existing tests passed.

Note

Low Risk
Scope is the TypeScript lint preset and TSDoc rule implementation; behavior is preserved with added resilience around tsdoc.json loading.

Overview
Removes eslint-plugin-tsdoc from @toruslabs/oxlint-config-typescript so the preset no longer pulls in @typescript-eslint/utils and a TypeScript 5 peer tree that breaks under TypeScript 7. The tsdoc/syntax rule is unchanged from a consumer perspective; it now runs through a shipped local plugin, tsdoc-plugin.mjs, built on @microsoft/tsdoc and @microsoft/tsdoc-config.

The new plugin still loads the nearest tsdoc.json, caches parsed config, reloads when the file changes or appears during a long lint, reports load/apply errors instead of crashing, and does not cache load failures (so fixes to extends files are picked up on the next file). vp pack includes the plugin; dependencies swap the ESLint plugin for the Microsoft packages. Tests cover custom tags, bad config, in-process reload, unreadable paths, and extends recovery.

Reviewed by Cursor Bugbot for commit 134e37f. Bugbot is set up for automated code reviews on this repo. Configure here.

@hieu-w
hieu-w requested review from a team as code owners November 9, 2026 08:22

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Stale Bugbot comment from a previous run.

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Stale Bugbot comment from a previous run.

if (configFile.fileNotFound) return { parser: new TSDocParser(configuration), applyError: undefined };
let applyError;
try {
configFile.configureParser(configuration);

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.

Config errors repeat once per linted file.

configureParser writes some errors into the config object itself, such as a supportForTags entry naming an undefined tag. Since the object is cached, every file adds another copy. File N reports "error loading TSDoc config file" with the same line N times, and the cached object's error list keeps growing. Upstream checks hasErrors before configuring, so it hides this on the first file. Here, the report comes after, so even the first file shows it.

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.

We should build the parser once, when the config is loaded, and cache it with the config. In configFor, store { configFile, ...parserFor(configFile) } in the map, and check isStale(entry.configFile). create then reads configFile, parser and applyError from that entry. This also stops rebuilding the parser setup for every file. Reusing one parser is safe because parseRange does not keep state between calls.

}
}

function configFor(filename) {

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.

An unreadable tsdoc.json crashes the rule instead of reporting.

If the file exists but can't be read (wrong permissions, or a folder named tsdoc.json), that read throws, and the exception escapes create. Upstream catches this and reports "error loading TSDoc config file" on line 1.

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 5705002. Configure here.

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.

Nit: No test fails if someone moves parserFor back into create. The new tests cover reloading and unreadable files, but not this.

return { parser: new TSDocParser(configuration), applyError };
}

function loadErrorEntry(configFilePath, error) {

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.

A broken extends file stays "broken" until restart.

The error can come from a base file pulled in through extends. E.g: made base.json unreadable and then fixed its permissions. The rule keep reporting EACCES because the top file never changed.

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 think we shouldn't cache the failure. In the catch, return { loadError: error } without calling configFiles.set. The next file then just retries loadFile, which costs a few file reads and only while the config is broken.

@chaitanyapotti
chaitanyapotti merged commit 488438d into main Nov 12, 2026
14 checks passed
@chaitanyapotti
chaitanyapotti deleted the fix/drop-eslint-plugin-tsdoc branch November 12, 2026 07:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants