Add Bikeshed support #712

kfranqueiro · 2025-11-25T14:20:36Z

This adds support to spec-generator for generating Bikeshed specs and issue lists, in a way that provides near-parity with the features of the CSSWG API.

Functionality included:

Setting what event level to die on (via HTML form or die-on)
Overriding the date in specs (via HTML form or md-date)
Setting the Prepare for TR flag (via HTML form or md-prepare-for-tr)
Arbitrary metadata overrides (via md-<key>)
Specifying a URL or uploading a standalone or tar file for both specs and issue lists
- This is particularly notable for the case of issue list URLs, as the CLI and CSSWG API do not support this
Expandable help section with details on the HTTP API

The most notable thing that isn't included is an equivalent to the CSSWG API's output=err, which I'd like to work on separately after this, to avoid making this PR even bigger.

The diff will be rather large, because I moved the majority of the code that had been in server.ts into generator/respec.ts in the process, as a lot of it was respec-specific. Now generator/bikeshed.ts and generator/respec.ts each export a similar API which server.ts calls after validating parameters, depending on the type parameter.

Other changes included in this PR:

Carries over die-on support to ReSpec, to maximize the amount of shared fields between the available generators
Carries over md-date and md-<key> support to ReSpec, to make it possible to override respecConfig properties even in case of file upload, which previously wasn't possible
Makes start function in server.ts async, to wait until the server is listening
Reformats all TS files and index.html to 2-space indent (from 4) to match other repos and default Prettier settings; since this PR results in a lot of changed lines already due to most code being added or relocated, it made sense to tackle this now as well (already discussed with Denis)
- Note: I tried running index.html through Prettier in the process, but ended up re-excluding it because of a couple of non-configurable decisions Prettier makes that I disagree with, primarily the inclusion of self-closing tags
- Also note this means that hiding whitespace in the PR diff will make it at least a little bit less noisy
Updates npm run watch to also restart on HTML changes
Updates npm test to correctly run all tests - and there are many more now, including tests across GET, POST, and POST with query string parameters, wherever applicable

This is what's used in other w3c repos I've encountered. Now is a good time to switch, since this PR is already heavily touching all of the TS code in the repo anyway.

- Adds md-<key> and die-on support to ReSpec - Expands tests and fixes test script to actually run all of them - Updates watch script to also restart on HTML change - TODO: Add die-on tests for ReSpec

util.ts

sidvishnoi · 2025-12-03T07:48:44Z

generators/respec.ts

+      throw new SpecGeneratorError(
+        `Did not generate, due to errors exceeding the allowed error level.`,
+      );


Can we have a way to expose the errors/warnings (or their counts) even with dieOn?

Good call-out; I've moved this code so it can share the same flow that currently produces headers regarding number of errors/warnings.

I want to do a future pass to actually include all errors when a run fails for this reason (for both ReSpec and Bikeshed) and to honor something like the output=err parameter that exists in the CSSWG API for Bikeshed, to allow seeing messages even if processing succeeds.

sidvishnoi · 2025-12-03T07:51:42Z

generators/respec.ts

+  const extract = tar.extract();
+  const uploadPath = await mkdtemp("uploads/");
+
+  return new Promise((resolve, reject) => {


Nit: if we're using Node.js v22+, we can use Promise.withResolvers.

Thanks for the tip; we currently run tests for v20, v22, and v24, which would preclude using this.

I'm +0 on it; I kind of like conceptually limiting the scope of resolve and reject. The instances in this PR wouldn't particularly benefit from the scope-collapsing of withResolvers (the only let present would still be necessary regardless), though reducing nesting would be nice for the instances in each generator.

@deniak, thoughts on dropping Node 20 from test.yml? (I would probably want to do it separately from this PR.)

generators/respec.ts

sidvishnoi · 2025-12-03T08:04:49Z

index.html

+          type="radio"
+          name="type"
+          value="respec"
+          checked


Small enhancement: If url parameter has ?type set, we can check the right radio buttons with script.

Is there a use case for this enhancement? I ask because this would expose multiple edge cases if the user were to change the Document type choice after loading this way:

Doing this client-side would override any previous user input within these radio buttons if the user were to refresh the page or revisit the form via browser history

Doing this server-side would avoid this, but would involve adding more complexity and dependencies to the Express setup (which I had considered doing earlier in this PR, but later decided to avoid when merging back to a single page)

GET parameters currently override POST parameters if both are present; I'd need to flip this, otherwise the form submission (which uses action="" to work regardless of base path) will break if a user changes the Document type, then performs a file upload with type in the URL

Changing this might be fine; many curl use cases found across GitHub use GET parameters with a POST request, but are unlikely to define the same parameter both ways

Co-authored-by: Sid Vishnoi <[email protected]>

kfranqueiro added 25 commits November 3, 2025 09:47

WIP Implement Bikeshed support

f2e3f06

Work around bikeshed JSON output bug

52e8359

Implement issues-list URL fetching

869e087

Hide spec-specific controls when issues-list is selected

71b5c1a

Improve spec/issues-specific show/hide behavior

458dbc2

Implement --die-on

1296da4

Add bikeshed tests, and clean up respec tests

6d13e05

Skip md-* params with no value

a228de3

Layout/style improvements/fixes

d3f1019

Install bikeshed during test workflow

4cd52e8

Re-extend test timeout for github workflow

ec3d14c

Work around bikeshed 5.3.5 regression

78b0d74

Add HTTP API docs

10162e7

Remove bikeshed workarounds that are no longer necessary as of 5.3.6

534a381

Standardize on 2-space indent (prettier default)

d6e52a1

This is what's used in other w3c repos I've encountered. Now is a good time to switch, since this PR is already heavily touching all of the TS code in the repo anyway.

README: Add note RE bikeshed version

b6e4661

Restructure as single page

631e3a6

- Adds md-<key> and die-on support to ReSpec - Expands tests and fixes test script to actually run all of them - Updates watch script to also restart on HTML change - TODO: Add die-on tests for ReSpec

Tweak test timeouts

f3a2c6a

Fix die-on behavior for ReSpec

e2c893a

Merge branch 'main' into kgf-bikeshed

fa30723

Add tests for type=respec + die-on

cfd6645

Simplify test suite setup to only start the server once

a37b2dc

Extend respec die-on suite timeout for CI

c26a38f

Cleanup

91f380f

Add more detailed docs around file types

263f3f1

kfranqueiro requested a review from deniak November 25, 2025 14:20

deniak requested changes Nov 27, 2025

View reviewed changes

util.ts Outdated Show resolved Hide resolved

Fix no-query-string case for mergeRequestParams

3097bf7

kfranqueiro requested a review from deniak December 2, 2025 14:04

Define limits for express-fileupload

ba384e0

kfranqueiro force-pushed the kgf-bikeshed branch from 535d0cf to ba384e0 Compare December 2, 2025 21:51

sidvishnoi reviewed Dec 3, 2025

View reviewed changes

kfranqueiro and others added 5 commits December 5, 2025 12:39

Apply suggestions from Sid's code review

3dc9516

Co-authored-by: Sid Vishnoi <[email protected]>

Fix formatting; apply Sid's base URL suggestion to one more instance

72616d9

Increase test timeout for CI again

1772d6b

Merge branch 'main' into kgf-bikeshed

4f94774

Move respec die-on logic to allow relaying same error/warning info

f6e4d08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add Bikeshed support #712

Add Bikeshed support #712

Uh oh!

kfranqueiro commented Nov 25, 2025 •

edited

Loading

Uh oh!

Uh oh!

sidvishnoi Dec 3, 2025

Uh oh!

kfranqueiro Dec 5, 2025

Uh oh!

sidvishnoi Dec 3, 2025

Uh oh!

kfranqueiro Dec 5, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sidvishnoi Dec 3, 2025

Uh oh!

kfranqueiro Dec 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Add Bikeshed support #712

Are you sure you want to change the base?

Add Bikeshed support #712

Uh oh!

Conversation

kfranqueiro commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

sidvishnoi Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

kfranqueiro Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

sidvishnoi Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

kfranqueiro Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sidvishnoi Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

kfranqueiro Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

kfranqueiro commented Nov 25, 2025 •

edited

Loading