reffy 11.0.1 → 11.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reffy",
-  "version": "11.0.1",
+  "version": "11.0.3",
   "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",
@@ -46,7 +46,7 @@
     "chai": "4.3.7",
     "mocha": "10.1.0",
     "nock": "13.2.9",
-    "respec": "32.3.0",
+    "respec": "32.4.0",
     "respec-hljs": "2.1.1",
     "rollup": "3.5.0"
   },

package/schemas/browserlib/extract-cssdfn.json

@@ -48,7 +48,8 @@
                 "values": { "$ref": "../common.json#/$defs/cssValues" }
               }
             }
-          }
+          },
+          "values": { "$ref": "../common.json#/$defs/cssValues" }
         }
       }
     },

package/schemas/common.json

@@ -43,11 +43,11 @@
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["name", "type", "value"],
+        "required": ["name", "type"],
         "additionalProperties": false,
         "properties": {
           "name": { "$ref": "#/$defs/cssValue" },
-          "type": { "type": "string", "enum": ["type", "function", "value"] },
+          "type": { "type": "string", "enum": ["type", "function", "value", "selector"] },
           "prose": { "type": "string" },
           "value": { "$ref": "#/$defs/cssValue" },
           "legacyValue": { "$ref": "#/$defs/cssValue" },

package/src/browserlib/extract-cssdfn.mjs

@@ -36,7 +36,9 @@ export default function () {
       warnings
     }),
     selectors: extractDfns({
-      selector: 'dfn[data-dfn-type=selector][data-export]',
+      selector: ['dfn[data-dfn-type=selector][data-export]:not([data-dfn-for])',
+                 'dfn[data-dfn-type=selector][data-export][data-dfn-for=""]'
+                ].join(','),
       extractor: extractTypedDfn,
       duplicates: 'reject',
       warnings
@@ -125,7 +127,8 @@ export default function () {
   const values = extractDfns({
     selector: ['dfn[data-dfn-type=value][data-dfn-for]:not([data-dfn-for=""])',
                'dfn[data-dfn-type=function][data-dfn-for]:not([data-dfn-for=""])',
-               'dfn[data-dfn-type=type][data-dfn-for]:not([data-dfn-for=""])'
+               'dfn[data-dfn-type=type][data-dfn-for]:not([data-dfn-for=""])',
+               'dfn[data-dfn-type=selector][data-dfn-for]:not([data-dfn-for=""])'
               ].join(','),
     extractor: extractTypedDfn,
     duplicates: 'push',
@@ -541,6 +544,39 @@ const parseProductionRule = (rule, { res = [], pureSyntax = false }) => {
 };
 
 
+/**
+ * Extract the definition name. If multiple linking texts are possible, the
+ * function will select the one that is a "syntax" definition. For instance, it
+ * will pick up "<identifier>" for "identifiers|<identifier>" in CSS 2:
+ * https://drafts.csswg.org/css2/#value-def-identifier
+ *
+ * The function throws if it cannot extract an obvious name from the definition.
+ * We may want to be smarter about that in the future, but this should really
+ * never happen in practice (the above "identifiers" example is the only one
+ * CSS value definition so far to have multiple linking texts)
+ */
+const getDfnName = dfn => {
+  if (dfn.getAttribute('data-lt')) {
+    const names = dfn.getAttribute('data-lt').split('|').map(normalize);
+    let name = names.find(n =>
+      n.startsWith('<') ||      // Looks like a "type"
+      n.startsWith('@') ||      // Looks like an "at-rule"
+      n.startsWith(':') ||      // Looks like a "descriptor"
+      n.endsWith('()'));        // Looks like a "function"
+    if (!name) {
+      if (names.length > 1) {
+        throw new Error(`Found multiple linking texts for dfn without any obvious one: ${names.join(', ')}`);
+      }
+      name = names[0];
+    }
+    return name;
+  }
+  else {
+    return dfn.textContent.trim();
+  }
+};
+
+
 /**
  * Extract the given dfn
  */
@@ -550,6 +586,7 @@ const extractTypedDfn = dfn => {
   const dfnType = dfn.getAttribute('data-dfn-type');
   const dfnFor = dfn.getAttribute('data-dfn-for');
   const parent = dfn.parentNode.cloneNode(true);
+  const fnRegExp = /^([a-zA-Z_][a-zA-Z0-9_\-]+)\([^\)]+\)$/;
 
   // Remove note references as in:
   // https://drafts.csswg.org/css-syntax-3/#the-anb-type
@@ -571,8 +608,17 @@ const extractTypedDfn = dfn => {
       // Don't attempt to parse pre tags at this stage, they are tricky to
       // split, we'll parse them as text and map them to the right definitions
       // afterwards.
-      const name = (dfn.getAttribute('data-lt') ?? dfn.textContent).trim();
-      res = { name };
+      // That said, we may be looking at a function definition on the right hand
+      // side of a production rule, as in the definition of "linear()" in
+      // css-easing-2: https://drafts.csswg.org/css-easing-2/#funcdef-linear
+      // In such a case, we still want to extract the function parameters
+      if (dfn.textContent.trim().match(fnRegExp)) {
+        const fn = dfn.textContent.trim().match(fnRegExp)[1];
+        res = parseProductionRule(`${fn}() = ${dfn.textContent.trim()}`, { pureSyntax: false });
+      }
+      else {
+        res = { name: getDfnName(dfn) };
+      }
     }
     else if (prod) {
       res = parseProductionRule(prod, { pureSyntax: true });
@@ -582,13 +628,12 @@ const extractTypedDfn = dfn => {
       // https://drafts.csswg.org/css-speech-1/#typedef-voice-volume-decibel
       // It may be worth checking but not an error per se.
       console.warn('[reffy]', `Found "=" next to definition of ${dfn.textContent.trim()} but no production rule. Did I miss something?`);
-      const name = (dfn.getAttribute('data-lt') ?? dfn.textContent).trim();
-      res = { name, prose: text.replace(/\s+/g, ' ') };
+      res = { name: getDfnName(dfn), prose: text.replace(/\s+/g, ' ') };
     }
   }
-  else if (dfn.textContent.trim().match(/^[a-zA-Z_][a-zA-Z0-9_\-]+\([^\)]+\)$/)) {
+  else if (dfn.textContent.trim().match(fnRegExp)) {
     // Definition is "prod(foo bar)", create a "prod() = prod(foo bar)" entry
-    const fn = dfn.textContent.trim().match(/^([a-zA-Z_][a-zA-Z0-9_\-]+)\([^\)]+\)$/)[1];
+    const fn = dfn.textContent.trim().match(fnRegExp)[1];
     res = parseProductionRule(`${fn}() = ${dfn.textContent.trim()}`, { pureSyntax: false });
   }
   else if (parent.nodeName === 'DT') {
@@ -622,20 +667,23 @@ const extractTypedDfn = dfn => {
         }
       });
 
-      const name = (dfn.getAttribute('data-lt') ?? dfn.textContent).trim();
-      res = { name, prose: dd.textContent.trim().replace(/\s+/g, ' ') };
+      res = {
+        name: getDfnName(dfn),
+        prose: dd.textContent.trim().replace(/\s+/g, ' ')
+      };
     }
   }
   else if (parent.nodeName === 'P') {
     // Definition is in regular prose, extract value from prose.
-    const name = (dfn.getAttribute('data-lt') ?? dfn.textContent).trim();
-    res = { name, prose: parent.textContent.trim().replace(/\s+/g, ' ') };
+    res = {
+      name: getDfnName(dfn),
+      prose: parent.textContent.trim().replace(/\s+/g, ' ')
+    };
   }
   else {
     // Definition is in a heading or a more complex structure, just list the
     // name for now.
-    const name = (dfn.getAttribute('data-lt') ?? dfn.textContent).trim();
-    res = { name };
+    res = { name: getDfnName(dfn) };
   }
 
   res.type = dfnType;

package/src/browserlib/extract-dfns.mjs

@@ -106,17 +106,18 @@ function hasValidType(el) {
   return isValid;
 }
 
-// Return true when definition is not already defined in the list,
+// Return true when exported definition is not already defined in the list,
 // Return false and issue a warning when it is already defined.
-function isNotAlreadyDefined(dfn, idx, list) {
+function isNotAlreadyExported(dfn, idx, list) {
   const first = list.find(d => d === dfn ||
-      (d.type === dfn.type &&
+      (d.access === 'public' && dfn.access === 'public' &&
+      d.type === dfn.type &&
       d.linkingText.length === dfn.linkingText.length &&
       d.linkingText.every(lt => dfn.linkingText.find(t => t == lt)) &&
       d.for.length === dfn.for.length &&
       d.for.every(lt => dfn.for.find(t => t === lt))));
   if (first !== dfn) {
-    console.warn('[reffy]', `Duplicate dfn found for "${dfn.linkingText[0]}", type="${dfn.type}", for="${dfn.for[0]}"`);
+    console.warn('[reffy]', `Duplicate dfn found for "${dfn.linkingText[0]}", type="${dfn.type}", for="${dfn.for[0]}", dupl=${dfn.href}, first=${first.href}`);
   }
   return first === dfn;
 }
@@ -267,7 +268,7 @@ export default function (spec, idToHeading = {}) {
       return !link || (node.textContent.trim() !== link.textContent.trim());
     })
     .map(node => definitionMapper(node, idToHeading, usesDfnDataModel))
-    .filter(isNotAlreadyDefined);
+    .filter(isNotAlreadyExported);
 }
 
 function preProcessEcmascript() {