@rolldown/pluginutils 1.0.0-beta.27

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/%40rolldown/pluginutils@1.0.0-beta.27
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40rolldown/pluginutils@1.0.0-beta.27
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:280d1059bef8715a9a1da41b2ebc1741c8f81ae145e3e11241f122488e87c11f","constraints":{"executionContext":"node"},"contract":["exactRegex creates an anchored RegExp matching only the exact string with special characters escaped","prefixRegex creates a RegExp matching strings starting with the given prefix","makeIdFiltersToMatchWithQuery adapts string globs and regular expressions to also match ids with query strings","and, or, not create composable logical filter expressions","query and queries construct query parameter filter expressions","interpreter evaluates include and exclude expressions sequentially against module code, id, and moduleType","interpreter correctly handles cleanUrl and query parameter checks"],"goal":"verify pkg:npm/%40rolldown/pluginutils@1.0.0-beta.27","kind":"HOW","packages":["pkg:npm/%40rolldown/pluginutils@1.0.0-beta.27"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40rolldown/pluginutils@1.0.0-beta.27"],"schemaVersion":1,"subject":"pkg:npm/%40rolldown/pluginutils@1.0.0-beta.27","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-rolldown-pluginutils",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-rolldown-pluginutils",
      "version": "1.0.0",
      "dependencies": {
        "@rolldown/pluginutils": "1.0.0-beta.27"
      }
    },
    "node_modules/@rolldown/pluginutils": {
      "version": "1.0.0-beta.27",
      "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-beta.27.tgz",
      "integrity": "sha512-+d0F4MKMCbeVUJwG96uQ4SgAznZNSq93I3V+9NHA4OpvqG8mRCpGdKmK8l/dl02h2CCDHwW2FqilnTyDcAnqjA==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-rolldown-pluginutils",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of @rolldown/pluginutils pattern matching and composable filter expressions",
  "type": "module",
  "main": "src/index.js",
  "dependencies": {
    "@rolldown/pluginutils": "1.0.0-beta.27"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40rolldown/pluginutils@1.0.0-beta.27",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40rolldown/pluginutils@1.0.0-beta.27"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

import {
  exactRegex,
  prefixRegex,
  makeIdFiltersToMatchWithQuery,
  and,
  or,
  not,
  id,
  moduleType,
  code,
  query,
  queries,
  include,
  exclude,
  interpreter,
  interpreterImpl,
  exprInterpreter,
} from '@rolldown/pluginutils';

/**
 * Creates an exact match regular expression with special characters escaped.
 *
 * @param {string} str - Literal string to match.
 * @param {string} [flags] - RegExp flags.
 * @returns {RegExp}
 */
export function createExactMatcher(str, flags) {
  return exactRegex(str, flags);
}

/**
 * Creates a prefix match regular expression with special characters escaped.
 *
 * @param {string} str - Prefix string to match.
 * @param {string} [flags] - RegExp flags.
 * @returns {RegExp}
 */
export function createPrefixMatcher(str, flags) {
  return prefixRegex(str, flags);
}

/**
 * Transforms an id glob or RegExp to also match ids that include query strings.
 *
 * @param {string|RegExp|Array<string|RegExp>} input - ID pattern or patterns.
 * @returns {string|RegExp|Array<string|RegExp>}
 */
export function matchWithQuery(input) {
  return makeIdFiltersToMatchWithQuery(input);
}

/**
 * Evaluates a set of composable filter expressions against module properties.
 *
 * @param {import('@rolldown/pluginutils').TopLevelFilterExpression|import('@rolldown/pluginutils').TopLevelFilterExpression[]} exprs
 * @param {string} [moduleCode]
 * @param {string} [moduleId]
 * @param {string} [modType]
 * @returns {boolean}
 */
export function evaluateFilter(exprs, moduleCode, moduleId, modType) {
  return interpreter(exprs, moduleCode, moduleId, modType);
}

export {
  exactRegex,
  prefixRegex,
  makeIdFiltersToMatchWithQuery,
  and,
  or,
  not,
  id,
  moduleType,
  code,
  query,
  queries,
  include,
  exclude,
  interpreter,
  interpreterImpl,
  exprInterpreter,
};

import assert from 'node:assert';
import {
  createExactMatcher,
  createPrefixMatcher,
  matchWithQuery,
  evaluateFilter,
  exactRegex,
  prefixRegex,
  makeIdFiltersToMatchWithQuery,
  and,
  or,
  not,
  id,
  moduleType,
  code,
  query,
  queries,
  include,
  exclude,
  interpreter,
} from '../src/index.js';

// 1. exactRegex creates an anchored RegExp matching only the exact string with special characters escaped
const exact = createExactMatcher('foo.bar+test');
assert.strictEqual(exact instanceof RegExp, true, 'exactRegex should return a RegExp instance');
assert.strictEqual(exact.test('foo.bar+test'), true, 'exactRegex matches exact string');
assert.strictEqual(exact.test('foo.bar+test-extra'), false, 'exactRegex does not match trailing content');
assert.strictEqual(exact.test('prefix-foo.bar+test'), false, 'exactRegex does not match leading content');

const exactDirect = exactRegex('a*b(c)');
assert.strictEqual(exactDirect.test('a*b(c)'), true);
assert.strictEqual(exactDirect.test('abc'), false);

// 2. prefixRegex creates a RegExp matching strings starting with the given prefix
const prefix = createPrefixMatcher('virtual:my-plugin');
assert.strictEqual(prefix instanceof RegExp, true, 'prefixRegex should return a RegExp instance');
assert.strictEqual(prefix.test('virtual:my-plugin'), true, 'prefixRegex matches exact prefix');
assert.strictEqual(prefix.test('virtual:my-plugin/subpath'), true, 'prefixRegex matches string with subpath');
assert.strictEqual(prefix.test('other:virtual:my-plugin'), false, 'prefixRegex rejects non-prefix matches');

const prefixDirect = prefixRegex('plugin:');
assert.strictEqual(prefixDirect.test('plugin:entry'), true);

// 3. makeIdFiltersToMatchWithQuery adapts string globs and regular expressions to also match ids with query strings
const stringFilter = matchWithQuery('**/*.js');
assert.strictEqual(stringFilter, '**/*.js{?*,}', 'String glob should be transformed with query suffix');

const regexFilter = matchWithQuery(/\.tsx?$/);
assert.strictEqual(regexFilter.test('src/index.ts'), true, 'Regex filter matches base file');
assert.strictEqual(regexFilter.test('src/index.ts?vue&type=script'), true, 'Regex filter matches file with query');
assert.strictEqual(regexFilter.test('src/index.tsx'), true, 'Regex filter matches alternative extension');
assert.strictEqual(regexFilter.test('src/index.js'), false, 'Regex filter does not match unrelated extension');

const arrayFilters = makeIdFiltersToMatchWithQuery(['*.js', /\.css$/]);
assert.strictEqual(Array.isArray(arrayFilters), true);
assert.strictEqual(arrayFilters[0], '*.js{?*,}');
assert.strictEqual(arrayFilters[1] instanceof RegExp, true);
assert.strictEqual(arrayFilters[1].test('styles.css?inline'), true);

// 4. and, or, not create composable logical filter expressions
const andExpr = and(id('index.js'), code('export default'));
assert.strictEqual(andExpr.kind, 'and');
assert.strictEqual(andExpr.args.length, 2);

const orExpr = or(id('a.js'), id('b.js'));
assert.strictEqual(orExpr.kind, 'or');
assert.strictEqual(orExpr.args.length, 2);

const notExpr = not(moduleType('json'));
assert.strictEqual(notExpr.kind, 'not');
assert.strictEqual(notExpr.expr.kind, 'moduleType');

// 5. query and queries construct query parameter filter expressions
const q = query('raw', true);
assert.strictEqual(q.kind, 'query');
assert.strictEqual(q.key, 'raw');
assert.strictEqual(q.pattern, true);

const qs = queries({ format: 'esm', minify: true });
assert.strictEqual(qs.kind, 'and');
assert.strictEqual(qs.args.length, 2);

// 6. interpreter evaluates include and exclude expressions sequentially against module code, id, and moduleType
const filterRules = [
  exclude(id(/node_modules/)),
  include(and(id(/\.js$/), code('import'))),
];

assert.strictEqual(
  evaluateFilter(filterRules, 'import fs from "node";', '/app/src/index.js', 'js'),
  true,
  'Matching include rule without exclude should evaluate to true'
);

assert.strictEqual(
  evaluateFilter(filterRules, 'import fs from "node";', '/app/node_modules/pkg/index.js', 'js'),
  false,
  'Exclude rule should take precedence and evaluate to false'
);

assert.strictEqual(
  evaluateFilter(filterRules, 'const a = 1;', '/app/src/index.js', 'js'),
  false,
  'Non-matching include rule should evaluate to false'
);

// 7. interpreter correctly handles cleanUrl and query parameter checks
const queryRules = [
  include(and(id('index.vue', { cleanUrl: true }), query('type', 'template'))),
];

assert.strictEqual(
  interpreter(queryRules, '<div>hello</div>', 'index.vue?type=template#hash', 'text'),
  true,
  'cleanUrl strips hash and query before matching ID, and query matcher checks search params'
);

assert.strictEqual(
  interpreter(queryRules, 'export default {}', 'index.vue?type=script', 'js'),
  false,
  'Non-matching query parameter should evaluate to false'
);

console.log('Contract tests passed successfully.');