Adjust index() in CSS package to also index descriptors (#1624)

The consolidated CSS file is mostly flat except for descriptors that are nested
under at-rules. The descriptors were still using an array. For consistency, the
`index()` function now indexes them by name too.

README was also updated to drop the note on at-rules syntax expansion since we
no longer do that. It also notes that the list of descriptors is not guaranteed
to be exhaustive.

Author: tidoust

packages/css/README.md

@@ -50,7 +50,7 @@ const ast = definitionSyntax.parse(properties['flex'].syntax);
 
 Additional keys may be set depending on the type of the CSS feature. For example:
 
-- At-rules have a `descriptors` key that contains the list of descriptors defined for the given at-rule.
+- At-rules have a `descriptors` key that contains the list of descriptors defined for the given at-rule. That list may not be exhaustive. For example, it does not contain descriptors that are only implicitly defined in specs, such as families of properties that some at-rules (e.g, `@position-try`) accept as descriptors.
 - Functions and types that are scoped to a property or other feature have a `for` key that contains the list of scoping features for that feature. A scoping feature may be a property, a function or a type. When the scoping feature is a type, its name in the `for` key is enclosed between `<` and `>`.
 - Properties have a `styleDeclaration` key that contains the list of IDL attribute names that the property generates. A number of other keys may be set to describe the property's initial value, animation type and other parameters.
 
@@ -59,7 +59,6 @@ Additional notes:
 - When a feature is defined across different levels in the same spec series, the definition from the latest level is used.
 - When a property is extended with new values in different specs, `href` links to the base definition and `syntax` is the union (using `|`) of the syntaxes of the base and extended definitions.
 - When new descriptors are defined for an at-rule in different specs, `descriptors` contains the merged list of known descriptors.
-- When specs define the syntax of an at-rule in terms of `<declaration-list>` or `<declaration-rule-list>`, the `syntax` key contains an "expanded" syntax that leverages the syntax of the at-rule's descriptors.
 
 ## Migrating from `mdn/data`
 

packages/css/index.js

@@ -24,6 +24,15 @@ async function index({folder = __dirname} = {}) {
         id += ' for ' + feature.for[0];
       }
       indexed[category][id] = feature;
+
+      // For at-rules, convert descriptors array into an indexed object too
+      if (feature.descriptors) {
+        const descriptors = feature.descriptors;
+        feature.descriptors = {};
+        for (const descriptor of descriptors) {
+          feature.descriptors[descriptor.name] = descriptor;
+        }
+      }
     }
   }
   return indexed;

test/css/consolidated.js

@@ -79,7 +79,16 @@ describe(`The consolidated CSS file`, async () => {
         `Not the right amount of ${pluralize(label)} in index`);
     }
 
-    assert(indexed.atrules['@import'], `No flex property in index`);
+    for (const [name, atrule] of Object.entries(indexed.atrules)) {
+      const initial = consolidated.atrules.find(a => a.name === name);
+      assert(initial, `No ${name} at-rule in index`);
+      assert.equal(
+        Object.keys(atrule.descriptors).length,
+        initial.descriptors.length,
+        `Not the right amount of descriptors for ${name} in index`);
+    }
+
+    assert(indexed.atrules['@import'], `No @import at-rule in index`);
     assert(indexed.functions['abs()'], `No abs() function in index`);
     assert(indexed.properties['flex'], `No flex property in index`);
     assert(indexed.selectors[':first-child'], `No :first-child selector in index`);