Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions .github/workflows/framework-baseline.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
name: framework-baseline

on:
pull_request:
paths:
- packages/framework-baseline/**
- packages/web-platform-tests/src/frameworks/**
- pnpm-lock.yaml
- .github/workflows/framework-baseline.yml
push:
branches: [main]
schedule:
# Mondays: catch framework releases that touch DOM members missing from the profiles.
- cron: '0 12 * * 1'
workflow_dispatch:

permissions:
contents: read

env:
MISE_IDIOMATIC_VERSION_FILE_ENABLE_TOOLS: node,pnpm

jobs:
pinned:
if: github.event_name != 'schedule'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c # v4.3.0
- run: pnpm install --frozen-lockfile
- run: pnpm --filter @bomb.sh/web-platform-tests build
- run: pnpm --filter @bomb.sh/framework-baseline run check

latest:
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c # v4.3.0
- run: pnpm install --frozen-lockfile
- run: >-
pnpm --filter @bomb.sh/framework-baseline update --latest
preact react react-dom solid-js svelte vue @happy-dom/global-registrator
- run: pnpm --filter @bomb.sh/web-platform-tests build
- name: Audit latest framework releases
shell: bash
run: |
set -o pipefail
echo '```' >> "$GITHUB_STEP_SUMMARY"
status=0
pnpm --filter @bomb.sh/framework-baseline --silent run check | tee -a "$GITHUB_STEP_SUMMARY" || status=$?
echo '```' >> "$GITHUB_STEP_SUMMARY"
exit $status
5 changes: 5 additions & 0 deletions knip.config.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,12 @@
import frameworkBaseline from './packages/framework-baseline/knip.json' with { type: 'json' };
import webPlatformTests from './packages/web-platform-tests/knip.json' with { type: 'json' };

export default {
workspaces: {
'packages/framework-baseline': {
entry: frameworkBaseline.entry,
project: frameworkBaseline.project,
},
'packages/web-platform-tests': {
entry: webPlatformTests.entry,
project: webPlatformTests.project,
Expand Down
1 change: 1 addition & 0 deletions packages/framework-baseline/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
.compiled/
21 changes: 21 additions & 0 deletions packages/framework-baseline/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# @bomb.sh/framework-baseline

Private tooling that records which DOM members each supported framework uses, then checks them against the [framework profiles](../web-platform-tests/src/frameworks/frameworks.ts) in `@bomb.sh/web-platform-tests`.

Each framework renders the same [scenario](src/scenario.ts) app into happy-dom: mount, events, adding and removing handlers, keyed list updates, conditionals, class/style, `innerHTML`, form bindings, SVG, focus, and unmount. The [recorder](src/recorder.ts) wraps every DOM prototype member and keeps only accesses whose direct caller is framework code; happy-dom internals and the scenario itself are ignored. Production builds are recorded, without hydration.

```sh
pnpm --filter @bomb.sh/web-platform-tests build
pnpm --filter @bomb.sh/framework-baseline run check # all frameworks
pnpm --filter @bomb.sh/framework-baseline run check react vue # selected
pnpm --filter @bomb.sh/framework-baseline run check --json
```

The check fails when a framework uses a member whose feature is missing from its profile, or a member that has no feature at all. Add the feature to [`features.ts`](../web-platform-tests/src/frameworks/features.ts) with the WPT cases covering it, or an empty map when none are adapted yet. Required features the scenario never observes are reported for information only: frameworks rely on event propagation without calling `dispatchEvent`, and some paths, such as hydration, are outside the scenario.

CI runs the check against the pinned versions on relevant changes and against the latest releases every Monday ([workflow](../../.github/workflows/framework-baseline.yml)).

Known recorder gaps:

- `style.color = …` assignments bypass happy-dom's prototype accessors and are not observed.
- happy-dom does not match `:checked` on `<option>`, so the Svelte driver binds its select manually and does not exercise Svelte's `bind:value` select path.
5 changes: 5 additions & 0 deletions packages/framework-baseline/knip.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"$schema": "https://unpkg.com/knip@6/schema.json",
"entry": ["src/audit.ts", "src/run.ts", "src/drivers/*.ts"],
"project": ["src/**/*.ts"]
}
25 changes: 25 additions & 0 deletions packages/framework-baseline/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
{
"name": "@bomb.sh/framework-baseline",
"version": "0.0.0",
"private": true,
"description": "Records the DOM members frameworks use and checks them against the WPT framework profiles",
"type": "module",
"license": "MIT",
"scripts": {
"check": "node src/audit.ts",
"typecheck": "tsc -p tsconfig.json"
},
"devDependencies": {
"@bomb.sh/web-platform-tests": "workspace:*",
"@happy-dom/global-registrator": "21.0.4",
"@types/react": "^19.3.0",
"@types/react-dom": "^19.3.0",
"preact": "11.2.0",
"react": "19.3.1",
"react-dom": "19.3.1",
"solid-js": "1.9.19",
"svelte": "5.57.3",
"typescript": "^6.0.2",
"vue": "3.5.45"
}
}
104 changes: 104 additions & 0 deletions packages/framework-baseline/src/audit.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
import { execFileSync } from 'node:child_process';
import { fileURLToPath } from 'node:url';
import { features, frameworks, type DOMFeature, type Framework } from '@bomb.sh/web-platform-tests';

/**
* Members frameworks are recorded touching that deliberately have no feature profile entry.
* Each needs a reason; anything else unmapped fails the audit.
*/
const untracked: Readonly<Record<string, string>> = {};

/** Solid and Svelte resolve their server builds without the browser condition. */
const conditions: Partial<Record<Framework, string[]>> = {
solid: ['--conditions=browser'],
svelte: ['--conditions=browser'],
};

interface Recording {
framework: Framework;
version: string;
/** `Owner#member access` → count. */
members: Record<string, number>;
}

interface Report {
framework: Framework;
version: string;
/** Observed features absent from the framework's profile. */
missing: DOMFeature[];
/** Observed members with no feature and no `untracked` reason. */
unmapped: string[];
/** Required features the scenario never observed (informational). */
unobserved: DOMFeature[];
}

const byMember = new Map<string, DOMFeature[]>();
for (const name of Object.keys(features) as DOMFeature[]) {
const member = name.includes('#') ? name.slice(name.indexOf('#') + 1) : name;
byMember.set(member, [...(byMember.get(member) ?? []), name]);
}

/** Owners differ between happy-dom prototypes and spec mixins; the interface name only breaks ties. */
function featureFor(owner: string, member: string): DOMFeature | undefined {
const candidates = byMember.get(member) ?? [];
if (candidates.length === 1) return candidates[0];
const match = candidates.find((name) => name.startsWith(`${owner}#`));
// Event object fields fall under the event model unless a member has its own feature.
return match ?? (owner.endsWith('Event') ? 'Event' : undefined);
}

function record(framework: Framework): Recording {
const run = fileURLToPath(new URL('run.ts', import.meta.url));
const output = execFileSync(
process.execPath,
[...(conditions[framework] ?? []), run, framework],
{
encoding: 'utf8',
stdio: ['ignore', 'pipe', 'inherit'],
},
);
return JSON.parse(output.trim().split('\n').at(-1)!) as Recording;
}

function audit({ framework, version, members }: Recording): Report {
const { required, optional } = frameworks[framework];
const profile = new Set<DOMFeature>([...required, ...Object.values(optional).flat()]);
const observed = new Set<DOMFeature>();
const unmapped = new Set<string>();
for (const entry of Object.keys(members)) {
const qualified = entry.slice(0, entry.indexOf(' '));
const [owner, member] = qualified.split('#') as [string, string];
const feature = featureFor(owner, member);
if (feature) observed.add(feature);
else if (!(qualified in untracked)) unmapped.add(qualified);
}
return {
framework,
version,
missing: [...observed].filter((name) => !profile.has(name)),
unmapped: [...unmapped],
unobserved: [...new Set(required)].filter((name) => !observed.has(name)),
};
}

const named = process.argv.slice(2).filter((arg) => !arg.startsWith('-')) as Framework[];
const selected = named.length ? named : (Object.keys(frameworks) as Framework[]);
const reports = selected.map((framework) => audit(record(framework)));

function summary(report: Report): string {
const status = report.missing.length || report.unmapped.length ? 'drift' : 'ok';
const lines = [`${report.framework}@${report.version}: ${status}`];
if (report.missing.length) lines.push(` missing from profile: ${report.missing.join(', ')}`);
if (report.unmapped.length) lines.push(` no feature: ${report.unmapped.join(', ')}`);
if (report.unobserved.length)
lines.push(` not observed (info): ${report.unobserved.join(', ')}`);
return lines.join('\n');
}

process.stdout.write(
process.argv.includes('--json')
? `${JSON.stringify(reports, null, '\t')}\n`
: `${reports.map(summary).join('\n\n')}\n`,
);

if (reports.some((report) => report.missing.length || report.unmapped.length)) process.exitCode = 1;
78 changes: 78 additions & 0 deletions packages/framework-baseline/src/drivers/preact.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
import { h, render, type JSX } from 'preact';
import { useState } from 'preact/hooks';
import type { Driver, Props } from '../scenario.ts';

function App(props: Props): JSX.Element {
const [count, setCount] = useState(0);
const [pings, setPings] = useState(0);
const [text, setText] = useState('');
const [area, setArea] = useState('');
const [checked, setChecked] = useState(false);
const [choice, setChoice] = useState('a');
return h(
'div',
{ id: 'app', class: props.className, style: { color: props.color } },
h('button', { id: 'inc', onClick: () => setCount((value) => value + 1) }, count),
h(
'button',
{ id: 'ping', onClick: props.listen ? () => setPings((value) => value + 1) : undefined },
pings,
),
h(
'ul',
null,
props.items.map((item) => h('li', { key: item }, item)),
),
props.show && h('p', { id: 'cond' }, 'shown'),
h('div', { id: 'html', dangerouslySetInnerHTML: { __html: props.html } }),
h('input', {
id: 'text',
value: text,
onInput: (event: Event) => setText((event.currentTarget as HTMLInputElement).value),
}),
h('span', { id: 'echo' }, text),
h('textarea', {
id: 'area',
value: area,
onInput: (event: Event) => setArea((event.currentTarget as HTMLTextAreaElement).value),
}),
h('span', { id: 'area-echo' }, area),
h('input', {
id: 'check',
type: 'checkbox',
checked,
onChange: (event: Event) => setChecked((event.currentTarget as HTMLInputElement).checked),
}),
h('span', { id: 'check-echo' }, checked ? 'on' : 'off'),
h(
'select',
{
id: 'choice',
value: choice,
onChange: (event: Event) => setChoice((event.currentTarget as HTMLSelectElement).value),
},
h('option', { value: 'a' }, 'A'),
h('option', { value: 'b' }, 'B'),
),
h('span', { id: 'choice-echo' }, choice),
h('svg', null, h('circle', { r: props.radius })),
);
}

/** Preact batches state updates on a timeout. */
const settle = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 0));

export const driver: Driver = {
async mount(container, props) {
render(h(App, props), container);
return {
async update(next) {
render(h(App, next), container);
},
flush: settle,
async unmount() {
render(null, container);
},
};
},
};
Loading
Loading