refactor: migrate @rolldown/pluginutils package from rolldown repository

.github/pr-labeler.yml

@@ -21,3 +21,7 @@
 'package: oxc-unshadowed-visitor':
   - changed-files:
       - any-glob-to-any-file: 'packages/oxc-unshadowed-visitor/**'
+
+'package: pluginutils':
+  - changed-files:
+      - any-glob-to-any-file: 'packages/pluginutils/**'

.github/workflows/ci.yml

@@ -57,6 +57,9 @@ jobs:
       - name: Test
         run: pnpm run test
 
+      - name: Type Tests
+        run: pnpm run test:types
+
   test-babel7:
     timeout-minutes: 20
     runs-on: ubuntu-latest
@@ -92,6 +95,9 @@ jobs:
       - name: Test
         run: pnpm run test
 
+      - name: Type Tests
+        run: pnpm run test:types
+
       - name: Lint (type check)
         run: pnpm run lint
 

.github/workflows/publish.yml

@@ -5,6 +5,7 @@ on:
     tags:
       - 'plugin-*'
       - 'oxc-unshadowed-visitor@*'
+      - 'pluginutils@*'
 
 jobs:
   publish:

.github/workflows/release-tag.yml

@@ -5,6 +5,7 @@ on:
     tags:
       - 'plugin-*'
       - 'oxc-unshadowed-visitor@*'
+      - 'pluginutils@*'
 
 jobs:
   release:

README.md

@@ -29,6 +29,7 @@ Official Rolldown plugins
 
 ### Other Packages
 
+- [`@rolldown/pluginutils`](https://github.com/rolldown/plugins/tree/main/packages/pluginutils) ([![NPM version][badge-npm-version-pluginutils]][url-npm-pluginutils]): plugin utilities (regex helpers, composable filters, Vite plugin filtering)
 - [`oxc-unshadowed-visitor`](https://github.com/rolldown/plugins/tree/main/packages/oxc-unshadowed-visitor) ([![NPM version][badge-npm-version-oxc-unshadowed-visitor]][url-npm-oxc-unshadowed-visitor]): scope-aware AST visitor that tracks references to specified names, filtering out those shadowed by local bindings
 
 ## License
@@ -41,9 +42,11 @@ Official Rolldown plugins
 [badge-npm-version-styled-jsx]: https://img.shields.io/npm/v/@rolldown/plugin-styled-jsx?color=brightgreen
 [badge-npm-version-transform-imports]: https://img.shields.io/npm/v/@rolldown/plugin-transform-imports?color=brightgreen
 [badge-npm-version-oxc-unshadowed-visitor]: https://img.shields.io/npm/v/oxc-unshadowed-visitor?color=brightgreen
+[badge-npm-version-pluginutils]: https://img.shields.io/npm/v/@rolldown/pluginutils?color=brightgreen
 [url-npm-babel]: https://npmx.dev/package/@rolldown/plugin-babel
 [url-npm-emotion]: https://npmx.dev/package/@rolldown/plugin-emotion
 [url-npm-jsx-remove-attributes]: https://npmx.dev/package/@rolldown/plugin-jsx-remove-attributes
 [url-npm-styled-jsx]: https://npmx.dev/package/@rolldown/plugin-styled-jsx
 [url-npm-transform-imports]: https://npmx.dev/package/@rolldown/plugin-transform-imports
 [url-npm-oxc-unshadowed-visitor]: https://npmx.dev/package/oxc-unshadowed-visitor
+[url-npm-pluginutils]: https://npmx.dev/package/@rolldown/pluginutils

package.json

@@ -8,6 +8,7 @@
     "lint": "oxlint --type-aware --type-check .",
     "test": "vitest",
     "test:e2e": "pnpm run --filter=./examples test",
+    "test:types": "pnpm -r test:types",
     "dev": "pnpm -r --parallel --filter=\"./packages/*\" run dev",
     "build": "pnpm -r --filter=\"./packages/*\" run build",
     "release": "pnpm run --filter=./scripts release",

packages/pluginutils/CHANGELOG.md

@@ -0,0 +1 @@
+

packages/pluginutils/README.md

@@ -0,0 +1,145 @@
+# @rolldown/pluginutils [![npm](https://img.shields.io/npm/v/@rolldown/pluginutils.svg)](https://npmx.dev/package/@rolldown/pluginutils)
+
+Plugin utilities for [Rolldown](https://rolldown.rs).
+
+Includes regex helpers for plugin hook filters, composable filter expressions, and a helper for filtering out Vite-serve-only plugins.
+
+## Install
+
+```bash
+pnpm add -D @rolldown/pluginutils
+```
+
+## Usage
+
+```ts
+import { exactRegex, prefixRegex, makeIdFiltersToMatchWithQuery } from '@rolldown/pluginutils'
+```
+
+All filter helpers are also exposed via the `/filter` subpath:
+
+```ts
+import { and, or, id, include } from '@rolldown/pluginutils/filter'
+```
+
+## Regex helpers
+
+### `exactRegex`
+
+- **Type:** `(str: string, flags?: string) => RegExp`
+
+Constructs a `RegExp` that matches the exact string specified. Useful as a plugin hook filter.
+
+```ts
+import { exactRegex } from '@rolldown/pluginutils'
+
+const plugin = {
+  name: 'plugin',
+  resolveId: {
+    filter: { id: exactRegex('foo') },
+    handler(id) {}, // only called for `foo`
+  },
+}
+```
+
+### `prefixRegex`
+
+- **Type:** `(str: string, flags?: string) => RegExp`
+
+Constructs a `RegExp` that matches values starting with the specified prefix.
+
+```ts
+import { prefixRegex } from '@rolldown/pluginutils'
+
+const plugin = {
+  name: 'plugin',
+  resolveId: {
+    filter: { id: prefixRegex('foo') },
+    handler(id) {}, // called for IDs starting with `foo`
+  },
+}
+```
+
+### `makeIdFiltersToMatchWithQuery`
+
+- **Type:** `(input: string | RegExp | (string | RegExp)[]) => string | RegExp | (string | RegExp)[]`
+
+Converts an id filter so that it also matches ids that include a query string.
+
+```ts
+import { makeIdFiltersToMatchWithQuery } from '@rolldown/pluginutils'
+
+const plugin = {
+  name: 'plugin',
+  transform: {
+    filter: { id: makeIdFiltersToMatchWithQuery(['**/*.js', /\.ts$/]) },
+    // Matches:
+    //   foo.js, foo.js?foo, foo.txt?foo.js,
+    //   foo.ts, foo.ts?foo, foo.txt?foo.ts
+    handler(code, id) {},
+  },
+}
+```
+
+## Composable filters
+
+[Composable filter expressions](https://rolldown.rs/apis/plugin-api/hook-filters#composable-filters) for use cases where a simple `id`/`include`/`exclude` is not enough. For example, when a plugin needs to combine `id`, `moduleType`, `code`, and `query` conditions.
+
+```ts
+import { and, code, id, include, interpreter, moduleType, or } from '@rolldown/pluginutils'
+
+const expr = include(and(or(id(/\.tsx?$/), id(/\.jsx?$/)), moduleType('tsx'), code(/import React/)))
+
+interpreter(expr, sourceCode, sourceId, 'tsx') // boolean
+```
+
+### Builders
+
+| Builder                        | Description                                                                                                                                              |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `and(...exprs)`                | All operands must match.                                                                                                                                 |
+| `or(...exprs)`                 | At least one operand must match.                                                                                                                         |
+| `not(expr)`                    | Negates the operand.                                                                                                                                     |
+| `id(pattern, params?)`         | Match the module id. `pattern` is `string` or `RegExp`. `params.cleanUrl` strips the query/hash before matching.                                         |
+| `importerId(pattern, params?)` | Match the importer's id. Same shape as `id`.                                                                                                             |
+| `moduleType(type)`             | Match Rolldown's module type (`'js'`, `'jsx'`, `'ts'`, `'tsx'`, `'json'`, `'text'`, `'base64'`, `'dataurl'`, `'binary'`, `'empty'`, or a custom string). |
+| `code(pattern)`                | Match the module source. `string` matches with `includes`; `RegExp` with `test`.                                                                         |
+| `query(key, pattern)`          | Match a single query parameter. `pattern` is `boolean` (key presence/truthiness), `string` (exact value), or `RegExp` (value pattern).                   |
+| `queries(obj)`                 | Shorthand for `and(...)` over multiple `query` entries.                                                                                                  |
+| `include(expr)`                | Top-level wrapper marking `expr` as an inclusion rule.                                                                                                   |
+| `exclude(expr)`                | Top-level wrapper marking `expr` as an exclusion rule.                                                                                                   |
+
+### `interpreter`
+
+- **Type:** `(exprs, code?, id?, moduleType?, importerId?) => boolean`
+
+Evaluates one or more top-level expressions against the given inputs. Returns `true` when at least one `include` matches and no `exclude` matches; when no `include` is present, defaults to `true` unless an `exclude` matches.
+
+The argument required by each expression must be provided. For example, evaluating an `id(...)` expression without passing `id` will throw.
+
+## `filterVitePlugins`
+
+- **Type:** `<T>(plugins: T | T[] | null | undefined | false) => T[]`
+
+Removes Vite plugins that target the dev server (`apply: 'serve'`) from a (possibly nested) plugin array. Plugins whose `apply` is a function are invoked with a `command: 'build'` context to decide. Useful when reusing a Vite plugin array inside a Rolldown config.
+
+```ts
+import { defineConfig } from 'rolldown'
+import { filterVitePlugins } from '@rolldown/pluginutils'
+import viteReact from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: filterVitePlugins([
+    viteReact(),
+    {
+      name: 'dev-only',
+      apply: 'serve', // filtered out
+      // ...
+    },
+  ]),
+})
+```
+
+## License
+
+MIT

packages/pluginutils/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@rolldown/pluginutils",
+  "version": "1.0.0",
+  "description": "Plugin utilities for Rolldown",
+  "keywords": [
+    "filter",
+    "plugin",
+    "rolldown"
+  ],
+  "homepage": "https://github.com/rolldown/plugins/tree/main/packages/pluginutils#readme",
+  "bugs": {
+    "url": "https://github.com/rolldown/plugins/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rolldown/plugins.git",
+    "directory": "packages/pluginutils"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./filter": "./dist/filter/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "dev": "tsdown --watch",
+    "build": "tsdown",
+    "test": "vitest --project pluginutils",
+    "test:types": "vitest --project pluginutils --typecheck.only",
+    "prepublishOnly": "pnpm run build"
+  },
+  "devDependencies": {
+    "@types/picomatch": "^4.0.3",
+    "picomatch": "^4.0.4",
+    "typescript": "^5.9.3"
+  }
+}