Add cssmerge post-processor to consolidate CSS extracts (#1849)

This adds a cssmerge post-processor at the crawl level that consolidates
definitions from CSS extracts into a single file. The CSS entries in the
resulting file are de-duplicated. The module starts with a number of comments
that detail the approach.

The intent is to create a view similar to that offered in MDN data to address
w3c/webref#1519

Comments at the top of the module also detail the main differences between the
two views. Main one is structural: we tend to use arrays in Webref so this code
also produces arrays, while MDN data uses indexed objects. It's easy to build
an indexed view from an array though.

Consolidation focuses on syntaxes and the code does not attempt to compute the
`units` list that exists in MDN data. It is easy to build that list by looking
at values of a handful of CSS properties. We could add it later on to the
consolidated file if that proves needed.

A couple of remaining open questions:
1. This creates a `css.json` file, similar to the `events.json` file that we
create when we post-process events. That's nice but it would be good to ship
that file in `@webref/css` in the end. That package already has a `CSS.json`
file at the root. How/Where to package the `css.json` file?
2. To de-duplicate, the most recent definition is used. That's the only
approach I can think of that can be automated. Consumers of MDN data may need
a more nuanced approach where the syntax better matches what core browsers
currently support. We can perhaps refine the process later on if needed with
some sort of patching mechanism (but my hunch is that this will remain a manual
process).

Author: tidoust

schemas/postprocessing/css.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "http://json-schema.org/schema#",
+  "$id": "https://github.com/w3c/reffy/blob/main/schemas/postprocessing/css.json",
+
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["atrules", "functions", "properties", "selectors", "types"],
+  "properties": {
+    "atrules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "descriptors"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string", "pattern": "^@" },
+          "href": { "$ref": "../common.json#/$defs/url" },
+          "value": { "$ref": "../common.json#/$defs/cssValue" },
+          "prose": { "type": "string" },
+          "descriptors": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["name", "for"],
+              "additionalProperties": true,
+              "properties": {
+                "name": { "type": "string" },
+                "for": { "type": "string" },
+                "href": { "$ref": "../common.json#/$defs/url" },
+                "value": { "$ref": "../common.json#/$defs/cssValue" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "functions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "type"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string", "pattern": "^<[^>]+>$|^.*()$" },
+          "for": { "type": "string" },
+          "href": { "$ref": "../common.json#/$defs/url" },
+          "type": { "type": "string", "enum": ["function"] },
+          "prose": { "type": "string" },
+          "value": { "$ref": "../common.json#/$defs/cssValue" }
+        }
+      }
+    },
+    "properties": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["name"],
+        "properties": {
+          "name": { "$ref": "../common.json#/$defs/cssPropertyName" },
+          "href": { "$ref": "../common.json#/$defs/url" },
+          "value": { "$ref": "../common.json#/$defs/cssValue" },
+          "legacyAliasOf": { "$ref": "../common.json#/$defs/cssPropertyName" },
+          "styleDeclaration": {
+            "type": "array",
+            "items": { "type": "string" },
+            "minItems": 1
+          }
+        }
+      }
+    },
+    "selectors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "$ref": "../common.json#/$defs/cssPropertyName" },
+          "href": { "$ref": "../common.json#/$defs/url" },
+          "prose": { "type": "string" },
+          "value": { "$ref": "../common.json#/$defs/cssValue" }
+        }
+      }
+    },
+    "types": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "type"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string", "pattern": "^<[^>]+>$|^.*()$" },
+          "for": { "type": "string" },
+          "href": { "$ref": "../common.json#/$defs/url" },
+          "type": { "type": "string", "enum": ["type"] },
+          "prose": { "type": "string" },
+          "value": { "$ref": "../common.json#/$defs/cssValue" }
+        }
+      }
+    }
+  }
+}

src/lib/post-processor.js

@@ -52,6 +52,7 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createFolderIfNeeded, shouldSaveToFile } from './util.js';
 import csscomplete from '../postprocessing/csscomplete.js';
+import cssmerge from '../postprocessing/cssmerge.js';
 import events from '../postprocessing/events.js';
 import idlnames from '../postprocessing/idlnames.js';
 import idlparsed from '../postprocessing/idlparsed.js';
@@ -64,6 +65,7 @@ import patchdfns from '../postprocessing/patch-dfns.js';
  */
 const modules = {
   csscomplete,
+  cssmerge,
   events,
   idlnames,
   idlparsed,