feat(linter/plugins): `oxlint` export types by overlookmotel · Pull Request #14163 · oxc-project/oxc

overlookmotel · 2025-09-26T14:17:14Z

oxlint package export TS types. defineRule and definePlugin now give you type-safety and intellisense.

Writing plugins in TS is only supported on versions of NodeJS which support type-stripping. Have not added a library (e.g. Jiti) to support older NodeJS versions.

Probably some of the types are wrong. But I think this is a decent start.

"Are the types wrong" (added in #14177) is reporting an error in index.d.ts:

import { VisitorObject as Visitor } from "../dist/generated/visit/visitor.js";
//                                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

because the file in dist/generated/visit is actually called visitor.d.ts (.d.ts, not .js).

I'm not sure if that's a mistake in Rolldown's bundling, "Are the types wrong" being too strict, or a genuine problem.

But regardless, TS seems to pick up the types from visitor.d.ts, so I think we can probably merge this and look into / fix it later.

overlookmotel · 2025-09-26T14:17:32Z

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

0-merge - adds this PR to the back of the merge queue
hotfix - for urgent hot fixes, skip the queue and merge this PR next

You must have a Graphite account in order to use the merge queue. Sign up using this link.

_{An organization admin has enabled the Graphite Merge Queue in this repository.} _{Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.}

This stack of pull requests is managed by Graphite. Learn more about stacking.

overlookmotel · 2025-09-26T14:29:56Z

@camc314 Would very much appreciate your help to improve the types / advise on whether more types should be exported, when you have time.

Please can you build dist folder locally, and check that the index.d.ts file looks OK?

let me check this out locally first

graphite-app · 2025-09-26T15:03:46Z

Merge activity

Sep 26, 3:03 PM UTC: overlookmotel added this pull request to the Graphite merge queue.
Sep 26, 3:06 PM UTC: The Graphite merge queue couldn't merge this PR because it was in draft mode.
Sep 28, 2:59 PM UTC: The merge label '0-merge' was detected. This PR will be added to the Graphite merge queue once it meets the requirements.
Sep 28, 2:59 PM UTC: camc314 added this pull request to the Graphite merge queue.
Sep 28, 3:05 PM UTC: Merged by the Graphite merge queue.

`oxlint` package export TS types. `defineRule` and `definePlugin` now give you type-safety and intellisense. Writing plugins in TS is only supported on versions of NodeJS which support type-stripping. Have not added a library (e.g. Jiti) to support older NodeJS versions. Probably some of the types are wrong, or incomplete, and we should maybe export more types. But I think this is a decent start.

overlookmotel · 2025-09-26T15:07:21Z

Oops. I added merge label to #14164 by accident, forgetting it was stacked on top of this one.

Have marked as draft to stop Graphite going ahead and merging it. @camc314 Please make this undraft and merge once you've had a chance to review it.

Copilot

Pull Request Overview

This PR adds TypeScript type support to the oxlint package, enabling type-safe plugin development with defineRule and definePlugin functions. The changes primarily focus on enabling TypeScript exports and adding type annotations to test fixtures.

Key changes:

Configure TypeScript declaration file generation for the main export
Add type exports for core interfaces like Context, Plugin, Rule, and Visitor
Update test fixtures to use TypeScript with proper type annotations

Reviewed Changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 2 comments.

File	Description
`apps/oxlint/tsdown.config.ts`	Configure separate build targets with TypeScript declarations enabled only for main export
`apps/oxlint/src-js/index.ts`	Export TypeScript types for public API
`apps/oxlint/package.json`	Add types field and dependencies for TypeScript support
Test fixture files	Convert JavaScript plugin files to TypeScript with type annotations

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

apps/oxlint/package.json

apps/oxlint/src-js/index.ts

overlookmotel · 2025-09-28T10:09:25Z

I've changed this so oxlint package now exports all types used in the external interface. I've checked carefully and the exports don't miss any.

#14200 converts all the plugins in text fixtures to TS, and the only oddity it threw up is this one: #14200 (review)

If that's OK, I think we're good to go.

camc314

do we need to update the npm/oxlint package.json with the exports?

camc314 · 2025-09-28T14:59:06Z

@camc314 Would very much appreciate your help to improve the types / advise on whether more types should be exported, when you have time.

Please can you build dist folder locally, and check that the index.d.ts file looks OK?

yes looked and all looks ok, i'm not certain the types for import * as ESTree from '@oxc-project/types'; are correct, but tricky to tell without a release

`oxlint` package export TS types. `defineRule` and `definePlugin` now give you type-safety and intellisense. Writing plugins in TS is only supported on versions of NodeJS which support type-stripping. Have not added a library (e.g. Jiti) to support older NodeJS versions. Probably some of the types are wrong. But I think this is a decent start. "Are the types wrong" (added in #14177) is reporting an error in `index.d.ts`: ```ts import { VisitorObject as Visitor } from "../dist/generated/visit/visitor.js"; // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``` because the file in `dist/generated/visit` is actually called `visitor.d.ts` (`.d.ts`, not `.js`). I'm not sure if that's a mistake in Rolldown's bundling, "Are the types wrong" being too strict, or a genuine problem. But regardless, TS seems to pick up the types from `visitor.d.ts`, so I think we can probably merge this and look into / fix it later.

overlookmotel · 2025-09-28T15:01:31Z

do we need to update the npm/oxlint package.json with the exports?

You're absolutely right! I'll add a PR to the stack to do that.

`oxlint` package export TS types. `defineRule` and `definePlugin` now give you type-safety and intellisense. Writing plugins in TS is only supported on versions of NodeJS which support type-stripping. Have not added a library (e.g. Jiti) to support older NodeJS versions. Probably some of the types are wrong. But I think this is a decent start. "Are the types wrong" (added in oxc-project#14177) is reporting an error in `index.d.ts`: ```ts import { VisitorObject as Visitor } from "../dist/generated/visit/visitor.js"; // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``` because the file in `dist/generated/visit` is actually called `visitor.d.ts` (`.d.ts`, not `.js`). I'm not sure if that's a mistake in Rolldown's bundling, "Are the types wrong" being too strict, or a genuine problem. But regardless, TS seems to pick up the types from `visitor.d.ts`, so I think we can probably merge this and look into / fix it later.

#14163 added types to `oxlint`, but neglected to add the types export to `npm/oxlint` package. Fix that.

## [1.19.0] - 2025-09-29 ### 🚀 Features - eb6345f linter/unicorn: Implement no-array-callback-reference (#14230) (camc314) - c64fa61 linter: Add `import/no-named-export` rule (#14229) (yefan) - d30159b linter: Fix for unsorted keys (#14225) (Hamir Mahal) - acd1266 linter/plugins: `oxlint` export types (#14163) (overlookmotel) - c0e461f linter: Add `unicorn/no-array-sort` rule (#14117) (Cason Kervis) - 00954de linter/plugins: Remove `--js-plugins` CLI option (#14134) (overlookmotel) - b4d716f linter/plugins: Move custom JS plugin config to `jsPlugins` (#14133) (overlookmotel) - 60f0b3f linter: Add fix for `preserve-caught-error` (#14104) (Cam McHenry) - 2d74c17 linter/no-multiple-resolved: Implement promise rule no-multiple-resolved (#13420) (Li Wei) - 5e05d1b semantic: Put jsdoc behind linter feature, remove runtime flag (#14140) (Boshen) - 71af1aa semantic: Add "linter" feature (#14139) (Boshen) - 1a6d7ae linter: Add `vue/max-props` rule (#14039) (yefan) - 9c3afea linter/plugins: Support fixes (#14094) (overlookmotel) - 1472147 linter: Move `no-unused-expressions` to correctness (#14099) (camchenry) - 8b7c784 linter: Add react/jsx-pascal-case rule (#12165) (Mikhail Baev) - c796966 linter/plugins: Add `meta` property to rules (#14089) (overlookmotel) ### 🐛 Bug Fixes - 39a171e linter: Get cli args on JS side, to avoid runtime inconsistencies (#14223) (camc314) - e045391 linter/plugins: Error on JS plugin with reserved name (#14226) (overlookmotel) - 6005015 linter: Correctly handle CRLF when inserting disable comments in framework files (#14228) (shulaoda) - 37f6b09 linter/plugins: Make `null` a valid value for `meta.fixable` (#14204) (overlookmotel) - 8879b5a linter/plugins: Add types export to `npm/oxlint` (#14219) (overlookmotel) - e37c435 language_server: Correct position for "ignore this rule for this file" in vue/astro/svelte files (#14187) (Sysix) - f8abab2 editor: Stricter path validation for `oxc.path.server` (#14202) (Sysix) - e9a14d1 linter/plugins: Allow `fix` function to return `undefined` (#14182) (overlookmotel) - ee9ecbe linter/plugins: Fix TS type for fixer methods (#14166) (overlookmotel) - 03d1684 linter/plugins: Output warning on first JS plugin load (#14165) (overlookmotel) - 9716f7c linter/plugins: Fix TS types (#14162) (overlookmotel) - d36d227 language_server: Don't lint file on code action when it is already ignored (#13976) (Sysix) - 353bfe7 language_server: Check if tsconfig path is a file before starting the `LintService` (#14126) (Sysix) - fc7026d linter: Add missing `NODE_TYPES`, `cfg_id` method for no-multiple-resolved (#14147) (camc314) - 180c790 linter: Fix false positive in `no-restricted-globals` (#14135) (yefan) - 4a4fce8 linter: Fix cli argument parsing (#14112) (camc314) - 9f3e2bc linter/plugins: Output errors thrown in JS plugins (#14096) (overlookmotel) - 357a2d3 linter: Add support for `tsgolint.exe` on Windows (#14101) (camchenry) - 2604b28 linter: Fix lint errors building `oxlint` (#14095) (overlookmotel) - d8e9cc5 linter/plugins: Validate type of `before` and `after` hooks (#14086) (overlookmotel) ### 🚜 Refactor - 4c3f1ac linter: Move `BUILT_IN_ERRORS` to utils file (#14221) (camc314) - 61ec0a7 linter/plugins: Simplify creation of `context` in `defineRule` ESLint shim (#14206) (overlookmotel) - 7a0eb57 language_server: Refactor ignore code action logic as a linter fix (#14183) (Sysix) - 3b1fe6f linter/plugins: Flatten directory structure of `dist` (#14199) (overlookmotel) - d52cba6 linter: Bump TSDown to latest (#14198) (overlookmotel) - 983dd1b linter/plugins: Add `Fixer` type (#14180) (overlookmotel) - 2f8b076 linter/plugins: Remove dead code (#14178) (overlookmotel) - 497236e semantic: Move AstNode::cfg_id to struct of arrays in AstNodes (#14137) (Boshen) - 5ba765c semantic: Move AstNode::flags to struct of arrays in AstNodes (#14136) (Boshen) - ffc810d linter: `preserve-caught-errors`: rename config and add docs (#14103) (camchenry) - f91db73 linter: Add `CompositeFix::merge_fixes_fallible` method (#14093) (overlookmotel) - e55ffe0 curly: Enhance curly brace rule configuration and handling (#13498) (Antoine Zanardi) - 2fb69fd eslint/eqeqeq: Clean up implementation and improve documentation (#13527) (Antoine Zanardi) - e69cd86 linter/plugins: `loadPluginImpl` return an object (#14087) (overlookmotel) ### 📚 Documentation - b83b1bd language_server: Docs for `Backend` struct (#14172) (Sysix) - 3106ba0 language_server: Docs for `WorkspaceWorker` (#14161) (Sysix) - b19f5bc linter/plugins: Improve JSDoc comments for `definePlugin` and `defineRule` (#14159) (overlookmotel) ### ⚡ Performance - 2575065 linter/plugins: Store if rule is fixable as boolean (#14205) (overlookmotel) - b6d2546 linter: Reduce string cloning in tsgo fixes (#14092) (overlookmotel) - c94c5dc linter: Remove allocation in `CompositeFix::merge_fixes` (#14090) (overlookmotel) ### 🧪 Testing - be58d6d language_server: Fix test for ServerFormatter in windows (#14210) (Sysix) - a9b603e linter/plugins: Convert all plugins in tests to TS (#14200) (overlookmotel) - 6ff3a23 linter/plugins: Add tests for `.ts`, `.mts`, `.cts` plugin files (#14164) (overlookmotel) - 8988d64 linter/plugins: Add line breaks to plugins files (#14181) (overlookmotel) - d7041c1 language_server: Add linebreaks for formatter snapshot (#14173) (Sysix) - 52db331 linter/plugins: Type-check test fixtures (#14158) (overlookmotel) - aca083a linter/plugins: Include stderr output in snapshots (#14155) (overlookmotel) - a3c8f46 linter/plugins: Do not run `pnpm` in tests (#14157) (overlookmotel) - d985aeb editor: Remove cross-module tests, covered by language server (#14156) (Sysix) - 0029b7f linter/plugins: Normalize line breaks in snapshots (#14154) (overlookmotel) - 7f2c101 linter/plugins: Specify path to `node` in tests (#14152) (overlookmotel) - fc14abc linter/plugins: Format test fixtures (#14125) (overlookmotel) - a6f965f linter/plugins: Simplify configs in test fixtures (#14124) (overlookmotel) - b1685f7 linter/plugins: Refactor tests (#14123) (overlookmotel) - 788e495 linter/plugins: Improve ESLint compat tests (#14119) (overlookmotel) - 5750077 linter/plugins: Fix file paths in snapshots (#14115) (overlookmotel) - 5c862f9 linter/plugins: Standardize test fixture structure (#14114) (overlookmotel) Co-authored-by: camc314 <18101008+camc314@users.noreply.github.com>

overlookmotel mentioned this pull request Sep 26, 2025

docs(linter/plugins): improve JSDoc comments for definePlugin and defineRule #14159

Merged

overlookmotel mentioned this pull request Sep 26, 2025

fix(linter/plugins): fix TS types #14162

Merged

github-actions bot added A-linter Area - Linter A-cli Area - CLI C-enhancement Category - New feature or request labels Sep 26, 2025

overlookmotel marked this pull request as ready for review September 26, 2025 14:28

overlookmotel requested a review from camc314 as a code owner September 26, 2025 14:28

overlookmotel assigned camc314 Sep 26, 2025

graphite-app bot changed the base branch from 09-26-fix_linter_plugins_fix_ts_types to graphite-base/14163 September 26, 2025 14:30

camc314 previously approved these changes Sep 26, 2025

View reviewed changes

graphite-app bot force-pushed the 09-26-feat_linter_plugins_oxlint_export_types branch from d43a5b9 to ee154b0 Compare September 26, 2025 14:36

graphite-app bot force-pushed the graphite-base/14163 branch from 41354ae to 9716f7c Compare September 26, 2025 14:36

graphite-app bot changed the base branch from graphite-base/14163 to main September 26, 2025 14:36

graphite-app bot force-pushed the 09-26-feat_linter_plugins_oxlint_export_types branch from ee154b0 to cdce8c2 Compare September 26, 2025 14:37

overlookmotel mentioned this pull request Sep 26, 2025

test(linter/plugins): add tests for .ts, .mts, .cts plugin files #14164

Merged

graphite-app bot added the 0-merge Merge with Graphite Merge Queue label Sep 26, 2025

graphite-app bot force-pushed the 09-26-feat_linter_plugins_oxlint_export_types branch from cdce8c2 to e2c1e24 Compare September 26, 2025 15:04

overlookmotel removed the 0-merge Merge with Graphite Merge Queue label Sep 26, 2025

overlookmotel marked this pull request as draft September 26, 2025 15:06

overlookmotel mentioned this pull request Sep 26, 2025

Linter plugins: Support plugins written in TypeScript #14009

Open

overlookmotel force-pushed the 09-26-feat_linter_plugins_oxlint_export_types branch from e2c1e24 to bb1d1cf Compare September 26, 2025 18:22

overlookmotel marked this pull request as ready for review September 27, 2025 07:28

Copilot AI review requested due to automatic review settings September 27, 2025 07:28

Copilot AI reviewed Sep 27, 2025

View reviewed changes

apps/oxlint/package.json Show resolved Hide resolved

apps/oxlint/src-js/index.ts Outdated Show resolved Hide resolved

overlookmotel marked this pull request as draft September 27, 2025 07:33

overlookmotel force-pushed the 09-26-feat_linter_plugins_oxlint_export_types branch from bb1d1cf to db91b09 Compare September 27, 2025 11:10

overlookmotel marked this pull request as ready for review September 27, 2025 11:16

overlookmotel requested a review from camc314 September 27, 2025 11:17

overlookmotel force-pushed the 09-26-feat_linter_plugins_oxlint_export_types branch from db91b09 to 846bc87 Compare September 28, 2025 08:51

This was referenced Sep 28, 2025

refactor(linter): bump TSDown to latest #14198

Merged

refactor(linter/plugins): flatten directory structure of dist #14199

Merged

test(linter/plugins): convert all plugins in tests to TS #14200

Merged

This was referenced Sep 28, 2025

fix(linter/plugins): make null a valid value for meta.fixable #14204

Merged

perf(linter/plugins): store if rule is fixable as boolean #14205

Merged

refactor(linter/plugins): simplify creation of context in defineRule ESLint shim #14206

Merged

camc314 approved these changes Sep 28, 2025

View reviewed changes

camc314 added the 0-merge Merge with Graphite Merge Queue label Sep 28, 2025

graphite-app bot force-pushed the 09-26-feat_linter_plugins_oxlint_export_types branch from 846bc87 to acd1266 Compare September 28, 2025 14:59

graphite-app bot merged commit acd1266 into main Sep 28, 2025
18 checks passed

graphite-app bot deleted the 09-26-feat_linter_plugins_oxlint_export_types branch September 28, 2025 15:05

graphite-app bot removed the 0-merge Merge with Graphite Merge Queue label Sep 28, 2025

overlookmotel mentioned this pull request Sep 28, 2025

fix(linter/plugins): add types export to npm/oxlint #14219

Merged

graphite-app bot pushed a commit that referenced this pull request Sep 28, 2025

fix(linter/plugins): add types export to npm/oxlint (#14219)

8879b5a

#14163 added types to `oxlint`, but neglected to add the types export to `npm/oxlint` package. Fix that.

Boshen mentioned this pull request Sep 29, 2025

release(oxlint): v1.19.0 #14231

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Comments

feat(linter/plugins): `oxlint` export types#14163

feat(linter/plugins): `oxlint` export types#14163
graphite-app[bot] merged 1 commit intomainfrom
09-26-feat_linter_plugins_oxlint_export_types

overlookmotel commented Sep 26, 2025 •

edited

Loading

Uh oh!

overlookmotel commented Sep 26, 2025 •

edited

Loading

Uh oh!

overlookmotel commented Sep 26, 2025 •

edited

Loading

Uh oh!

graphite-app bot commented Sep 26, 2025 •

edited

Loading

Uh oh!

overlookmotel commented Sep 26, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

overlookmotel commented Sep 28, 2025 •

edited

Loading

Uh oh!

camc314 left a comment

Uh oh!

camc314 commented Sep 28, 2025

Uh oh!

overlookmotel commented Sep 28, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Comments

Conversation

overlookmotel commented Sep 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

overlookmotel commented Sep 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How to use the Graphite Merge Queue

Uh oh!

overlookmotel commented Sep 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

graphite-app bot commented Sep 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

overlookmotel commented Sep 26, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

overlookmotel commented Sep 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

camc314 left a comment

Choose a reason for hiding this comment

Uh oh!

camc314 commented Sep 28, 2025

Uh oh!

overlookmotel commented Sep 28, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

overlookmotel commented Sep 26, 2025 •

edited

Loading

overlookmotel commented Sep 26, 2025 •

edited

Loading

overlookmotel commented Sep 26, 2025 •

edited

Loading

graphite-app bot commented Sep 26, 2025 •

edited

Loading

overlookmotel commented Sep 28, 2025 •

edited

Loading