reffy 18.8.2 → 19.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reffy",
-  "version": "18.8.2",
+  "version": "19.0.1",
   "description": "W3C/WHATWG spec dependencies exploration companion. Features a short set of tools to study spec references as well as WebIDL term definitions and references found in W3C specifications.",
   "repository": {
     "type": "git",
@@ -37,15 +37,15 @@
     "ajv-formats": "3.0.1",
     "commander": "14.0.0",
     "fetch-filecache-for-crawling": "5.1.1",
-    "puppeteer": "24.10.0",
+    "puppeteer": "24.10.1",
     "semver": "^7.3.5",
     "web-specs": "3.53.0",
     "webidl2": "24.4.1"
   },
   "devDependencies": {
-    "respec": "35.4.0",
+    "respec": "35.4.1",
     "respec-hljs": "2.1.1",
-    "rollup": "4.42.0",
+    "rollup": "4.43.0",
     "undici": "^7.0.0"
   },
   "overrides": {

package/schemas/postprocessing/css.json

@@ -2,6 +2,16 @@
   "$schema": "http://json-schema.org/schema#",
   "$id": "https://github.com/w3c/reffy/blob/main/schemas/postprocessing/css.json",
 
+  "$defs": {
+    "scopes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1
+    }
+  },
+
   "type": "object",
   "additionalProperties": false,
   "required": ["atrules", "functions", "properties", "selectors", "types"],
@@ -15,7 +25,7 @@
         "properties": {
           "name": { "type": "string", "pattern": "^@" },
           "href": { "$ref": "../common.json#/$defs/url" },
-          "value": { "$ref": "../common.json#/$defs/cssValue" },
+          "syntax": { "$ref": "../common.json#/$defs/cssValue" },
           "prose": { "type": "string" },
           "descriptors": {
             "type": "array",
@@ -27,7 +37,7 @@
                 "name": { "type": "string" },
                 "for": { "type": "string" },
                 "href": { "$ref": "../common.json#/$defs/url" },
-                "value": { "$ref": "../common.json#/$defs/cssValue" }
+                "syntax": { "$ref": "../common.json#/$defs/cssValue" }
               }
             }
           }
@@ -41,12 +51,12 @@
         "required": ["name", "type"],
         "additionalProperties": false,
         "properties": {
-          "name": { "type": "string", "pattern": "^<[^>]+>$|^.*()$" },
-          "for": { "type": "string" },
+          "name": { "type": "string", "pattern": "^.*()$" },
+          "for": { "$ref": "#/$defs/scopes" },
           "href": { "$ref": "../common.json#/$defs/url" },
           "type": { "type": "string", "enum": ["function"] },
           "prose": { "type": "string" },
-          "value": { "$ref": "../common.json#/$defs/cssValue" }
+          "syntax": { "$ref": "../common.json#/$defs/cssValue" }
         }
       }
     },
@@ -59,7 +69,7 @@
         "properties": {
           "name": { "$ref": "../common.json#/$defs/cssPropertyName" },
           "href": { "$ref": "../common.json#/$defs/url" },
-          "value": { "$ref": "../common.json#/$defs/cssValue" },
+          "syntax": { "$ref": "../common.json#/$defs/cssValue" },
           "legacyAliasOf": { "$ref": "../common.json#/$defs/cssPropertyName" },
           "styleDeclaration": {
             "type": "array",
@@ -79,7 +89,7 @@
           "name": { "$ref": "../common.json#/$defs/cssPropertyName" },
           "href": { "$ref": "../common.json#/$defs/url" },
           "prose": { "type": "string" },
-          "value": { "$ref": "../common.json#/$defs/cssValue" }
+          "syntax": { "$ref": "../common.json#/$defs/cssValue" }
         }
       }
     },
@@ -90,12 +100,12 @@
         "required": ["name", "type"],
         "additionalProperties": false,
         "properties": {
-          "name": { "type": "string", "pattern": "^<[^>]+>$|^.*()$" },
-          "for": { "type": "string" },
+          "name": { "type": "string", "pattern": "^[a-zA-Z0-9-\\+\\(\\)\\[\\]\\{\\}]+$" },
+          "for": { "$ref": "#/$defs/scopes" },
           "href": { "$ref": "../common.json#/$defs/url" },
           "type": { "type": "string", "enum": ["type"] },
           "prose": { "type": "string" },
-          "value": { "$ref": "../common.json#/$defs/cssValue" }
+          "syntax": { "$ref": "../common.json#/$defs/cssValue" }
         }
       }
     }

package/src/postprocessing/cssmerge.js

@@ -13,7 +13,7 @@
  * In CSS extracts, functions and types that are defined for another construct
  * appear under the `values` key of that construct entry. In the resulting
  * construct, they get copied to the root lists under `functions` or `types`,
- * and get a `for` key that contains the name of the construct that they are
+ * and get a `for` key that contains the list of constructs that they are
  * defined for.
  *
  * CSS properties that are defined in one spec and extended in other specs get
@@ -51,12 +51,10 @@
  * - This code uses arrays for lists, MDN data uses indexed objects.
  * - This code lists scoped definitions with a `for` key. MDN data only has
  * unscoped definitions.
- * - This code stores syntaxes in a `value` key, MDN data uses a `syntax` key.
  * - This code stores syntaxes of functions and types directly in the
  * `functions` and `types` lists. MDN data stores them in a separate `syntaxes`
  * category. The `syntaxes` view can be built by merging the `functions` and
  * `types` lists.
- * - This code keeps the surrounding `<>` for type names, MDN data does not.
  *
  * Module runs at the crawl level to create a `css.json` file.
  */
@@ -158,14 +156,27 @@ export default {
         // ... and since we're looping through features, let's get rid
         // of inner value definitions, which we no longer need
         // (interesting ones were already copied to the root level)
+        // Let's also turn `value` keys into `syntax` keys because that's
+        // a better name and that matches what MDN data uses, and drop
+        // enclosing `<` and `>` for type names (type names that look like
+        // functions should be .
         if (feature.values) {
           delete feature.values;
         }
+        if (feature.value) {
+          feature.syntax = feature.value;
+          delete feature.value;
+        }
         for (const descriptor of feature.descriptors ?? []) {
           if (descriptor.values) {
             delete descriptor.values;
           }
+          if (descriptor.value) {
+            descriptor.syntax = descriptor.value;
+            delete descriptor.value;
+          }
         }
+        feature.name = unwrapName(feature.name);
 
         const featureId = getFeatureId(feature);
         if (!featureDfns[featureId]) {
@@ -178,10 +189,10 @@ export default {
       // (that has some known syntax) in the most recent level. Move that base
       // definition to the beginning of the array and get rid of other base
       // definitions.
-      // (Note: the code throws an error if duplicates of base definitions in
-      // unrelated specs still exist)
+      // (Note: the code chooses one definition if duplicates of base
+      // definitions in unrelated specs still exist)
       for (const [name, dfns] of Object.entries(featureDfns)) {
-        let actualDfns = dfns.filter(dfn => dfn.value);
+        let actualDfns = dfns.filter(dfn => dfn.syntax);
         if (actualDfns.length === 0) {
           actualDfns = dfns.filter(dfn => !dfn.newValues);
         }
@@ -214,7 +225,7 @@ export default {
           if (dfn === baseDfn) {
             continue;
           }
-          if (baseDfn.value && dfn.newValues) {
+          if (baseDfn.syntax && dfn.newValues) {
             const newerDfn = dfns.find(d =>
               d !== dfn &&
               d.newValues === dfn.newValues &&
@@ -224,7 +235,7 @@ export default {
               // the older one
               continue;
             }
-            baseDfn.value += ' | ' + dfn.newValues;
+            baseDfn.syntax += ' | ' + dfn.newValues;
           }
           if (baseDfn.descriptors && dfn.descriptors?.length > 0) {
             baseDfn.descriptors.push(...dfn.descriptors.filter(desc => {
@@ -253,28 +264,28 @@ export default {
             if (unscoped) {
               // Only keep the scoped feature if it has a known syntax that
               // differs from the unscoped feature
-              return feature.value && feature.value !== unscoped.value;
+              return feature.syntax && feature.syntax !== unscoped.syntax;
             }
           }
           return true;
         })
         .map(feature => {
           if (feature.descriptors?.length > 0 &&
-              feature.value?.match(/{ <declaration-(rule-)?list> }/)) {
+              feature.syntax?.match(/{ <declaration-(rule-)?list> }/)) {
             // Note: More advanced logic would allow to get rid of enclosing
             // grouping constructs when there's no ambiguity. We'll stick to
             // simple logic for now.
             const syntax = feature.descriptors
               .map(desc => {
                 if (desc.name.startsWith('@')) {
-                  return `[ ${desc.value} ]`;
+                  return `[ ${desc.syntax} ]`;
                 }
                 else {
-                  return `[ ${desc.name}: [ ${desc.value} ]; ]`;
+                  return `[ ${desc.name}: [ ${desc.syntax} ]; ]`;
                 }
               })
               .join(' ||\n  ');
-            feature.value = feature.value.replace(
+            feature.syntax = feature.syntax.replace(
               /{ <declaration-(rule-)?list> }/,
               '{\n  ' + syntax + '\n}');
           }
@@ -286,16 +297,42 @@ export default {
       // Various CSS properties are "legacy aliases of" another property. Use the
       // syntax of the other property for these.
       for (const feature of categorized[category]) {
-        if (feature.legacyAliasOf && !feature.value) {
+        if (feature.legacyAliasOf && !feature.syntax) {
           const target = categorized[category].find(f =>
             f.name === feature.legacyAliasOf && !f.for);
           if (!target) {
             throw new Error(`${feature.name} is a legacy alias of unknown ${f.legacyAliasOf}`);
           }
-          feature.value = target.value;
+          feature.syntax = target.syntax;
         }
       }
 
+      // The same feature may be defined for multiple scopes.
+      // To ease indexing and lookup by feature name, let's merge the scopes
+      // when possible, turning the `for` key into an array. This will not get
+      // rid of all scoping duplicates, but should still make the feature name
+      // unique for all but a handful of them.
+      categorized[category] = categorized[category]
+        .map((feature, idx, list) => {
+          const first = list.find(f => f.href === feature.href);
+          if (first === feature) {
+            if (feature.for) {
+              feature.for = [feature.for];
+            }
+            return feature;
+          }
+          // Not the first time we see this feature, let's merge scopes.
+          // Both scopes should be defined as there is no way to author a
+          // single dfn that defines a feature both as scoped and unscoped.
+          if (!first.for || !feature.for) {
+            throw new Error(`Feature ${feature.name} defined both as unscoped and scoped within the same dfn, see ${feature.href}`);
+          }
+          first.for.push(feature.for);
+          first.for.sort();
+          return null;
+        })
+        .filter(feature => !!feature);
+
       // Let's sort lists before we return to ease human-readability and
       // avoid non-substantive diff
       for (const feature of categorized[category]) {
@@ -313,13 +350,14 @@ export default {
 
 
 /**
- * Return the identifier of a feature, taking scoping construct into account
+ * Return the identifier of a feature, taking scoping construct(s) into account
  * when needed.
  */
 function getFeatureId(feature) {
   let featureId = feature.name;
   if (feature.for) {
-    featureId += ' for ' + feature.for;
+    featureId += ' for ' +
+      (Array.isArray(feature.for) ? feature.for.join(',') : feature.for);
   }
   return featureId;
 }
@@ -338,3 +376,18 @@ function decorateFeaturesWithSpec(data, spec) {
     }
   }
 }
+
+
+/**
+ * Unwrap (type) name
+ *
+ * Note: names that appear in other categories are never enclosed in `<`
+ * and `>`
+ */
+function unwrapName(name) {
+  const typeMatch = name.match(/^<([^>]+)>$/);
+  if (typeMatch) {
+    return typeMatch[1];
+  }
+  return name;
+}