reffy 6.2.0 → 6.2.1

package/src/browserlib/extract-references.mjs

@@ -1,203 +1,203 @@
-import getGenerator from './get-generator.mjs';
-
-
-/**
- * Extract the list of references from the "References" appendix of the
- * current document.
- *
- * Notes:
- * - By definition, this function does not return the specifications that
- * the current document references in the prose but failed to add to the
- * "References" appendix.
- * - The function throws when no references could be found
- *
- * @function
- * @public
- * @return {Object} An object with a "normative" and/or an "informative"
- *   property that list references as they appear in the "References".
- */
-export default function () {
-  const generator = getGenerator();
-  const extractionRules = getExtractionRules(generator);
-  const references = extractReferences(extractionRules);
-  if (references?.normative.length || references?.informative.length) {
-    return references;
-  }
-  else {
-    return null;
-  }
-}
-
-
-
-/**
- * Given the name of the generator used to create the document,
- * return the rules to use to extract references.
- *
- * @function
- * @private
- * @param {String} generator The well-known generator used to create the doc,
- *   null if unknown
- * @return {Object} Relevant extraction rules (or null if no rules seem to apply).
- */
-function getExtractionRules(generator) {
-  const extractionRules = {
-    bikeshed: {
-      generator: "Bikeshed",
-      listSelector: {
-        normative: "#normative + dl",
-        informative: "#informative + dl"
-      }
-    },
-    respec: {
-      generator: "ReSpec",
-      listSelector: {
-        normative: "#normative-references > dl",
-        informative: "#informative-references > dl"
-      }
-    }
-  };
-
-  return (generator ? extractionRules[generator] : null);
-}
-
-
-/**
- * Skip next siblings until another tag with the given name is found
- *
- * @function
- * @private
- * @param {Node} node The DOM node to use as starting point
- * @param {String} name The sibling name to find
- * @return {Node} The next sibling with the given name, null if not found
- */
-function nextTag(node, name) {
-  let nextEl = node.nextElementSibling;
-  while(nextEl && nextEl.tagName !== name.toUpperCase()) {
-    nextEl = nextEl.nextElementSibling;
-  }
-  return nextEl;
-}
-
-
-/**
- * Given a markup definition list, parse and return the list of references
- *
- * @function
- * @param {Node} referenceList The "dl" to parse
- * @param {Object} options Parsing options, set "filterInformative" to put
- *   references flagged as "non-normative" to a separate returned list
- * @return {Array} An array whose first item is the list of references and the
- *   second item the list of "non-normative" references (the second item is only
- *   set when "filterInformative" is set)
- */
-function parseReferences(referenceList, options) {
-  var defaultRef = [], informativeRef = [];
-  options = options || {};
-  [].forEach.call(referenceList.querySelectorAll("dt"), function (dt) {
-    var ref = {};
-    ref.name = dt.textContent.replace(/[\[\] \n]/g, '');
-    var desc = nextTag(dt, "dd");
-    if (!desc || !ref.name) {
-      return;
-    }
-    ref.url = desc.querySelector('a[href^="http"]')?.href ?? "";
-    if (options.filterInformative &&
-        desc.textContent.match(/non-normative/i)) {
-      return informativeRef.push(ref);
-    }
-    defaultRef.push(ref);
-  });
-  return [defaultRef, informativeRef];
-};
-
-const textMatch = re => n => n.textContent.match(re);
-
-/**
- * Extract references from generic documents that we could not associate with
- * any particular set of extraction rules.
- *
- * @function
- * @private
- * @return {Object} A list of references.
- */
-function extractReferencesWithoutRules() {
-  const references = {
-    normative: [],
-    informative: []
-  };
-  const anchors = [...document.querySelectorAll("h1, h2, h3")];
-  const referenceHeadings = anchors.filter(textMatch(/references/i));
-  if (!referenceHeadings.length) {
-    return references;
-  }
-  if (referenceHeadings.length > 1) {
-    const normative = referenceHeadings.find(textMatch(/normative/i));
-    if (normative) {
-      const nList = nextTag(normative, "dl");
-      if (nList) {
-        references.normative = parseReferences(nList)[0];
-      }
-    }
-    const informative = referenceHeadings.find(textMatch(/informative/i));
-    if (informative) {
-      const iList = nextTag(informative, "dl");
-      if (iList) {
-        references.informative = parseReferences(iList)[0];
-      }
-    }
-    if (informative || normative) {
-      return references;
-    }
-  }
-
-  // If there are still multiple reference headings,
-  // keep only the last one
-  const referenceHeading = referenceHeadings.pop();
-  const list = nextTag(referenceHeading, "dl");
-  if (list) {
-    const refs = parseReferences(list, { filterInformative: true });
-    references.normative = refs[0];
-    references.informative = refs[1];
-  }
-  return references;
-}
-
-
-/**
- * Extract references from the given document
- *
- * @function
- * @private
- * @param {Object} rules Extraction rules to use
- * @return {Object} A list of references.
- */
-function extractReferences(rules) {
-  if (!rules) {
-    return extractReferencesWithoutRules();
-  }
-  if (!rules.listSelector ||
-      !rules.listSelector.normative) {
-    throw new Error("Extraction rules for the list of references are incorrect");
-  }
-  const generator = rules.generator || "an unknown generator";
-
-  const references = {
-    normative: [],
-    informative: []
-  };
-  ["normative", "informative"].forEach(function (referenceType) {
-    const referenceList = document.querySelector(rules.listSelector[referenceType]);
-    if (referenceList) {
-      const refs = parseReferences(referenceList, {
-        filterInformative: (referenceType === "normative")
-      });
-      references[referenceType] = references[referenceType].concat(refs[0]);
-      if (referenceType === "normative") {
-          references.informative = references.informative.concat(refs[1]);
-      }
-    }
-  });
-
-  return references;
-}
+import getGenerator from './get-generator.mjs';
+
+
+/**
+ * Extract the list of references from the "References" appendix of the
+ * current document.
+ *
+ * Notes:
+ * - By definition, this function does not return the specifications that
+ * the current document references in the prose but failed to add to the
+ * "References" appendix.
+ * - The function throws when no references could be found
+ *
+ * @function
+ * @public
+ * @return {Object} An object with a "normative" and/or an "informative"
+ *   property that list references as they appear in the "References".
+ */
+export default function () {
+  const generator = getGenerator();
+  const extractionRules = getExtractionRules(generator);
+  const references = extractReferences(extractionRules);
+  if (references?.normative.length || references?.informative.length) {
+    return references;
+  }
+  else {
+    return null;
+  }
+}
+
+
+
+/**
+ * Given the name of the generator used to create the document,
+ * return the rules to use to extract references.
+ *
+ * @function
+ * @private
+ * @param {String} generator The well-known generator used to create the doc,
+ *   null if unknown
+ * @return {Object} Relevant extraction rules (or null if no rules seem to apply).
+ */
+function getExtractionRules(generator) {
+  const extractionRules = {
+    bikeshed: {
+      generator: "Bikeshed",
+      listSelector: {
+        normative: "#normative + dl",
+        informative: "#informative + dl"
+      }
+    },
+    respec: {
+      generator: "ReSpec",
+      listSelector: {
+        normative: "#normative-references > dl",
+        informative: "#informative-references > dl"
+      }
+    }
+  };
+
+  return (generator ? extractionRules[generator] : null);
+}
+
+
+/**
+ * Skip next siblings until another tag with the given name is found
+ *
+ * @function
+ * @private
+ * @param {Node} node The DOM node to use as starting point
+ * @param {String} name The sibling name to find
+ * @return {Node} The next sibling with the given name, null if not found
+ */
+function nextTag(node, name) {
+  let nextEl = node.nextElementSibling;
+  while(nextEl && nextEl.tagName !== name.toUpperCase()) {
+    nextEl = nextEl.nextElementSibling;
+  }
+  return nextEl;
+}
+
+
+/**
+ * Given a markup definition list, parse and return the list of references
+ *
+ * @function
+ * @param {Node} referenceList The "dl" to parse
+ * @param {Object} options Parsing options, set "filterInformative" to put
+ *   references flagged as "non-normative" to a separate returned list
+ * @return {Array} An array whose first item is the list of references and the
+ *   second item the list of "non-normative" references (the second item is only
+ *   set when "filterInformative" is set)
+ */
+function parseReferences(referenceList, options) {
+  var defaultRef = [], informativeRef = [];
+  options = options || {};
+  [].forEach.call(referenceList.querySelectorAll("dt"), function (dt) {
+    var ref = {};
+    ref.name = dt.textContent.replace(/[\[\] \n]/g, '');
+    var desc = nextTag(dt, "dd");
+    if (!desc || !ref.name) {
+      return;
+    }
+    ref.url = desc.querySelector('a[href^="http"]')?.href ?? "";
+    if (options.filterInformative &&
+        desc.textContent.match(/non-normative/i)) {
+      return informativeRef.push(ref);
+    }
+    defaultRef.push(ref);
+  });
+  return [defaultRef, informativeRef];
+};
+
+const textMatch = re => n => n.textContent.match(re);
+
+/**
+ * Extract references from generic documents that we could not associate with
+ * any particular set of extraction rules.
+ *
+ * @function
+ * @private
+ * @return {Object} A list of references.
+ */
+function extractReferencesWithoutRules() {
+  const references = {
+    normative: [],
+    informative: []
+  };
+  const anchors = [...document.querySelectorAll("h1, h2, h3")];
+  const referenceHeadings = anchors.filter(textMatch(/references/i));
+  if (!referenceHeadings.length) {
+    return references;
+  }
+  if (referenceHeadings.length > 1) {
+    const normative = referenceHeadings.find(textMatch(/normative/i));
+    if (normative) {
+      const nList = nextTag(normative, "dl");
+      if (nList) {
+        references.normative = parseReferences(nList)[0];
+      }
+    }
+    const informative = referenceHeadings.find(textMatch(/informative/i));
+    if (informative) {
+      const iList = nextTag(informative, "dl");
+      if (iList) {
+        references.informative = parseReferences(iList)[0];
+      }
+    }
+    if (informative || normative) {
+      return references;
+    }
+  }
+
+  // If there are still multiple reference headings,
+  // keep only the last one
+  const referenceHeading = referenceHeadings.pop();
+  const list = nextTag(referenceHeading, "dl");
+  if (list) {
+    const refs = parseReferences(list, { filterInformative: true });
+    references.normative = refs[0];
+    references.informative = refs[1];
+  }
+  return references;
+}
+
+
+/**
+ * Extract references from the given document
+ *
+ * @function
+ * @private
+ * @param {Object} rules Extraction rules to use
+ * @return {Object} A list of references.
+ */
+function extractReferences(rules) {
+  if (!rules) {
+    return extractReferencesWithoutRules();
+  }
+  if (!rules.listSelector ||
+      !rules.listSelector.normative) {
+    throw new Error("Extraction rules for the list of references are incorrect");
+  }
+  const generator = rules.generator || "an unknown generator";
+
+  const references = {
+    normative: [],
+    informative: []
+  };
+  ["normative", "informative"].forEach(function (referenceType) {
+    const referenceList = document.querySelector(rules.listSelector[referenceType]);
+    if (referenceList) {
+      const refs = parseReferences(referenceList, {
+        filterInformative: (referenceType === "normative")
+      });
+      references[referenceType] = references[referenceType].concat(refs[0]);
+      if (referenceType === "normative") {
+          references.informative = references.informative.concat(refs[1]);
+      }
+    }
+  });
+
+  return references;
+}

package/src/browserlib/extract-webidl.mjs

@@ -1,135 +1,135 @@
-import getGenerator from './get-generator.mjs';
-import informativeSelector from './informative-selector.mjs';
-
-/**
- * Extract the list of WebIDL definitions in the current spec
- *
- * @function
- * @public 
- * @return {Promise} The promise to get a dump of the IDL definitions, or
- *   an empty string if the spec does not contain any IDL.
- */
-export default function () {
-    const generator = getGenerator();
-    let idl = '';
-    if (generator === 'bikeshed') {
-        idl = extractBikeshedIdl();
-    }
-    else if (document.title.startsWith('Web IDL')) {
-        // IDL content in the Web IDL spec are... examples,
-        // not real definitions
-    }
-    else {
-        // Most non-ReSpec specs still follow the ReSpec conventions
-        // for IDL definitions
-        idl = extractRespecIdl();
-    }
-
-    if (idl) {
-        // Remove trailing spaces and use spaces throughout
-        idl = idl
-            .replace(/\s+$/gm, '\n')
-            .replace(/\t/g, '  ')
-            .trim();
-    }
-    return idl;
-}
-
-
-/**
- * Extract IDL definitions from a Bikeshed spec
- *
- * Note Bikeshed summarizes IDL definitions in an appendix. This is
- * what the code uses.
- */
-function extractBikeshedIdl() {
-    const idlHeading = document.getElementById('idl-index');
-    if (idlHeading) {
-        const nextEl = idlHeading.nextElementSibling;
-        if (nextEl) {
-            return nextEl.textContent;
-        }
-        else {
-            throw new Error('Could not find IDL in IDL index');
-        }
-    }
-    else {
-        // the document may have been generated with "omit idl-index"
-        // in which case, we try the simple way
-        return extractRespecIdl();
-    }
-}
-
-
-/**
- * Extract IDL definitions from a ReSpec spec, and in practice from
- * most other specs as well.
- *
- * The function tries all known patterns used to define IDL content, making
- * sure that it only extracts elements once.
- */
-function extractRespecIdl() {
-    // Helper function that trims individual lines in an IDL block,
-    // removing as much space as possible from the beginning of the page
-    // while preserving indentation. Rules followed:
-    // - Always trim the first line
-    // - Remove whitespaces from the end of each line
-    // - Replace lines that contain spaces with empty lines
-    // - Drop same number of leading whitespaces from all other lines
-    const trimIdlSpaces = idl => {
-        const lines = idl.trim().split('\n');
-        const toRemove = lines
-            .slice(1)
-            .filter(line => line.search(/\S/) > -1)
-            .reduce(
-                (min, line) => Math.min(min, line.search(/\S/)),
-                Number.MAX_VALUE);
-        return lines
-            .map(line => {
-                let firstRealChat = line.search(/\S/);
-                if (firstRealChat === -1) {
-                    return '';
-                }
-                else if (firstRealChat === 0) {
-                    return line.replace(/\s+$/, '');
-                }
-                else {
-                    return line.substring(toRemove).replace(/\s+$/, '');
-                }
-            })
-            .join('\n');
-    };
-
-    // Detect the IDL index appendix if there's one (to exclude it)
-    const idlEl = document.querySelector('#idl-index pre') ||
-        document.querySelector('.chapter-idl pre'); // SVG 2 draft
-
-    let idl = [
-        'pre.idl:not(.exclude):not(.extract):not(#actual-idl-index)',
-        'pre:not(.exclude):not(.extract) > code.idl-code:not(.exclude):not(.extract)',
-        'pre:not(.exclude):not(.extract) > code.idl:not(.exclude):not(.extract)',
-        'div.idl-code:not(.exclude):not(.extract) > pre:not(.exclude):not(.extract)',
-        'pre.widl:not(.exclude):not(.extract)'
-    ]
-        .map(sel => [...document.querySelectorAll(sel)])
-        .reduce((res, elements) => res.concat(elements), [])
-        .filter(el => el !== idlEl)
-        .filter((el, idx, self) => self.indexOf(el) === idx)
-        .filter(el => !el.closest(informativeSelector))
-        .map(el => el.cloneNode(true))
-        .map(el => {
-            const header = el.querySelector('.idlHeader');
-            if (header) {
-                header.remove();
-            }
-            const tests = el.querySelector('details.respec-tests-details');
-            if (tests) {
-                tests.remove();
-            }
-            return el;
-        })
-        .map(el => trimIdlSpaces(el.textContent))
-        .join('\n\n');
-
-    return idl;
+import getGenerator from './get-generator.mjs';
+import informativeSelector from './informative-selector.mjs';
+
+/**
+ * Extract the list of WebIDL definitions in the current spec
+ *
+ * @function
+ * @public 
+ * @return {Promise} The promise to get a dump of the IDL definitions, or
+ *   an empty string if the spec does not contain any IDL.
+ */
+export default function () {
+    const generator = getGenerator();
+    let idl = '';
+    if (generator === 'bikeshed') {
+        idl = extractBikeshedIdl();
+    }
+    else if (document.title.startsWith('Web IDL')) {
+        // IDL content in the Web IDL spec are... examples,
+        // not real definitions
+    }
+    else {
+        // Most non-ReSpec specs still follow the ReSpec conventions
+        // for IDL definitions
+        idl = extractRespecIdl();
+    }
+
+    if (idl) {
+        // Remove trailing spaces and use spaces throughout
+        idl = idl
+            .replace(/\s+$/gm, '\n')
+            .replace(/\t/g, '  ')
+            .trim();
+    }
+    return idl;
+}
+
+
+/**
+ * Extract IDL definitions from a Bikeshed spec
+ *
+ * Note Bikeshed summarizes IDL definitions in an appendix. This is
+ * what the code uses.
+ */
+function extractBikeshedIdl() {
+    const idlHeading = document.getElementById('idl-index');
+    if (idlHeading) {
+        const nextEl = idlHeading.nextElementSibling;
+        if (nextEl) {
+            return nextEl.textContent;
+        }
+        else {
+            throw new Error('Could not find IDL in IDL index');
+        }
+    }
+    else {
+        // the document may have been generated with "omit idl-index"
+        // in which case, we try the simple way
+        return extractRespecIdl();
+    }
+}
+
+
+/**
+ * Extract IDL definitions from a ReSpec spec, and in practice from
+ * most other specs as well.
+ *
+ * The function tries all known patterns used to define IDL content, making
+ * sure that it only extracts elements once.
+ */
+function extractRespecIdl() {
+    // Helper function that trims individual lines in an IDL block,
+    // removing as much space as possible from the beginning of the page
+    // while preserving indentation. Rules followed:
+    // - Always trim the first line
+    // - Remove whitespaces from the end of each line
+    // - Replace lines that contain spaces with empty lines
+    // - Drop same number of leading whitespaces from all other lines
+    const trimIdlSpaces = idl => {
+        const lines = idl.trim().split('\n');
+        const toRemove = lines
+            .slice(1)
+            .filter(line => line.search(/\S/) > -1)
+            .reduce(
+                (min, line) => Math.min(min, line.search(/\S/)),
+                Number.MAX_VALUE);
+        return lines
+            .map(line => {
+                let firstRealChat = line.search(/\S/);
+                if (firstRealChat === -1) {
+                    return '';
+                }
+                else if (firstRealChat === 0) {
+                    return line.replace(/\s+$/, '');
+                }
+                else {
+                    return line.substring(toRemove).replace(/\s+$/, '');
+                }
+            })
+            .join('\n');
+    };
+
+    // Detect the IDL index appendix if there's one (to exclude it)
+    const idlEl = document.querySelector('#idl-index pre') ||
+        document.querySelector('.chapter-idl pre'); // SVG 2 draft
+
+    let idl = [
+        'pre.idl:not(.exclude):not(.extract):not(#actual-idl-index)',
+        'pre:not(.exclude):not(.extract) > code.idl-code:not(.exclude):not(.extract)',
+        'pre:not(.exclude):not(.extract) > code.idl:not(.exclude):not(.extract)',
+        'div.idl-code:not(.exclude):not(.extract) > pre:not(.exclude):not(.extract)',
+        'pre.widl:not(.exclude):not(.extract)'
+    ]
+        .map(sel => [...document.querySelectorAll(sel)])
+        .reduce((res, elements) => res.concat(elements), [])
+        .filter(el => el !== idlEl)
+        .filter((el, idx, self) => self.indexOf(el) === idx)
+        .filter(el => !el.closest(informativeSelector))
+        .map(el => el.cloneNode(true))
+        .map(el => {
+            const header = el.querySelector('.idlHeader');
+            if (header) {
+                header.remove();
+            }
+            const tests = el.querySelector('details.respec-tests-details');
+            if (tests) {
+                tests.remove();
+            }
+            return el;
+        })
+        .map(el => trimIdlSpaces(el.textContent))
+        .join('\n\n');
+
+    return idl;
 }