Add pinned WPT and isolated Node test tooling

.github/workflows/node.js.yml

@@ -2,27 +2,24 @@ name: nwsapi
 
 on:
   push:
-    branches:
-      - main
+    branches: [master]
   pull_request:
-    branches:
-      - main
+    branches: [master]
 
 jobs:
-  build:
+  node:
     runs-on: ubuntu-latest
-
     steps:
-    - name: Checkout repository
-      uses: actions/checkout@v2
-
-    - name: Setup Node.js
-      uses: actions/setup-node@v2
-      with:
-        node-version: '14'
-
-    - name: Install dependencies
-      run: npm install
-
-    - name: Run tests
-      run: npm testIs the NodeJS yaml configuration needed in my "nwsapi" repository ?
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 (2026-07-20)
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 (2026-07-14)
+        with:
+          node-version: '26'
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+      - run: npm test
+      - run: npm run min
+      - run: npm run upstream:clone
+      - run: npm run upstream:verify
+      - run: npx playwright install --with-deps chromium
+      - run: npm run test:upstream

.gitignore

@@ -1,3 +1,6 @@
-node_modules/
-package-lock.json
+**/node_modules/
+/dist/nwsapi.min.js
+/playwright-report/
+/test-results/
+/upstream/
 yarn.lock

.gitmodules

@@ -0,0 +1,11 @@
+# wpt-7aed663 sha256:9954c30501783f0c12ea5026a94cf988c8c5d2ac3ed51279cbfdd7476f92c393
+[submodule "upstream/wpt"]
+	ignore = dirty
+	ref = 7aed6630812b20e6eec2a2e40594f8dfda036e00
+	path = upstream/wpt
+	url = https://github.com/web-platform-tests/wpt.git
+	branch = master
+	shallow = true
+	sparse-checkout = resources common dom/nodes css/selectors
+	verify = npm run test:upstream
+# no-release-tag: web-platform-tests publishes no release tags; pinned by ref on master

README.md

@@ -66,6 +66,23 @@ Add the adapter's `css-tree` peer dependency to `package.json`:
 Run `npm install` or `pnpm install`. jsdom will use nwsapi for queries and stylesheet
 matching. The existing nwsapi factory API and selector support are unchanged.
 
+## Development
+
+Run the development tools with Node.js ≥ 22. This does not change the library's
+runtime support.
+CI runs lint, Node tests, the build and WPT in one Node.js 26 job.
+
+```sh
+npm ci
+npm test
+npm run lint
+npm run min
+```
+
+Node tests need no browser or WPT checkout. See [upstream testing](docs/upstream.md)
+for Chromium setup and known failures. `npm run clean` removes only the generated
+`dist/nwsapi.min.js` bundle.
+
 ## Supported Selectors
 
 Here is a list of all the CSS2/CSS3/CSS4 [Supported selectors](https://github.com/dperini/nwsapi/wiki/CSS-supported-selectors).

docs/upstream.md

@@ -0,0 +1,56 @@
+# Upstream selector tests
+
+The WPT runner loads `src/nwsapi.js` before each test page and installs it
+as the selector engine. It checks 41 pages listed in `test/upstream/manifest.mjs`.
+This is a selected suite, not the complete web-platform-tests project.
+
+Run with Node.js ≥ 22.
+
+```sh
+npm ci
+npm run upstream:clone
+npm run upstream:verify
+npx playwright install chromium
+npm run test:upstream
+```
+
+`.gitmodules` pins WPT to `7aed6630812b20e6eec2a2e40594f8dfda036e00`.
+The helper fetches a shallow, sparse checkout and verifies its manifest hash.
+The checkout is ignored, not a Git submodule. Do not edit its files.
+Clone and sparse-restoration commands reject paths that resolve outside the
+repository and refuse dirty existing checkouts before changing them.
+
+Node tests run separately with `npm test`; they need neither WPT nor Chromium.
+The browser server binds localhost and refuses an occupied port.
+
+## Baseline
+
+`test/upstream/expectations.json` records failures measured against unchanged
+master `fe15bc3ae8f76725a13b329aad2efbe3fa75f9a4` using Chromium 151.0.7922.34.
+It is not the earlier aggregate branch's baseline. Pending fixes keep their
+regression assertions in their own PRs; a baseline entry does not replace them.
+
+This baseline contains 352 expected failures, versus 336 in the aggregate.
+The 16 additional failures cover relative `:has()` arguments and detached
+elements. Their correction belongs to the relational-selector extraction.
+
+Unexpected failures fail the run. Unexpected passes are reported for cleanup.
+To regenerate after reviewing an engine or upstream change:
+
+```sh
+WPT_UPDATE_EXPECTATIONS=1 npm run test:upstream
+```
+
+Review the diff before committing. Do not use baseline updates to hide regressions.
+Filtered updates are rejected; baseline writes use one worker.
+
+Use `WPT_FILTER` for a subtest-name substring or `/regex/`, and `WPT_SECTION`
+for a selector-section substring. List sections with
+`node test/upstream/sections.mjs`.
+
+## Lint baseline
+
+The flat configuration checks source and new tooling. `eslint-suppressions.json`
+records two existing source findings: undefined `isInstanceof` in `byClass`
+and an unused assignment to `source`. They are not repaired by this tooling PR.
+Remove each suppression when its engine correction lands.

eslint-suppressions.json

@@ -0,0 +1,10 @@
+{
+  "src/nwsapi.js": {
+    "no-undef": {
+      "count": 1
+    },
+    "no-useless-assignment": {
+      "count": 1
+    }
+  }
+}

eslint.config.mjs

@@ -0,0 +1,78 @@
+import { defineConfig, globalIgnores } from 'eslint/config';
+import js from '@eslint/js';
+import globals from 'globals';
+
+export default defineConfig([
+  globalIgnores([
+    'dist/',
+    'node_modules/',
+    'upstream/',
+    'test-results/',
+    'playwright-report/',
+    // legacy browser-run suites, not lintable as modern JS
+    'test/css3-compat/',
+    'test/css3-escape/',
+    'test/html5/',
+    'test/jquery/',
+    'test/jsvm/',
+    'test/prototype/',
+    'test/quirks/',
+    'test/scope/',
+    'test/scotch/',
+    'test/slick/',
+    'test/speed/',
+    'test/w3c/',
+    'test/W3C-Selector-tests/',
+    'test/wpt/',
+    'test/xml/',
+    'build/',
+  ]),
+  js.configs.recommended,
+  {
+    files: ['src/**/*.js'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'script',
+      globals: {
+        ...globals.browser,
+        ...globals.commonjs,
+        ...globals.amd,
+        NW: 'readonly',
+      },
+    },
+    rules: {
+      'no-console': 'off',
+      'no-unused-vars': 'off',
+      'no-cond-assign': 'off',
+      'no-control-regex': 'off',
+      'no-useless-escape': 'off',
+      'no-redeclare': 'off',
+      'no-empty': 'off',
+
+      'default-case': 'error',
+      'no-duplicate-case': 'error',
+      'radix': 'error',
+      'no-with': 'error',
+    },
+  },
+  {
+    files: ['**/*.cjs'],
+    languageOptions: {
+      sourceType: 'commonjs',
+      globals: globals.node,
+    },
+  },
+  {
+    files: ['**/*.mjs'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: {
+        ...globals.nodeBuiltin,
+      },
+    },
+    rules: {
+      'no-console': 'off',
+    },
+  },
+]);