reffy 19.0.0 → 19.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reffy",
-  "version": "19.0.0",
+  "version": "19.1.0",
   "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.1",
+    "puppeteer": "24.12.1",
     "semver": "^7.3.5",
-    "web-specs": "3.53.0",
+    "web-specs": "3.56.0",
     "webidl2": "24.4.1"
   },
   "devDependencies": {
-    "respec": "35.4.1",
+    "respec": "35.4.2",
     "respec-hljs": "2.1.1",
-    "rollup": "4.43.0",
+    "rollup": "4.44.2",
     "undici": "^7.0.0"
   },
   "overrides": {

package/schemas/browserlib/extract-dfns.json

@@ -2,6 +2,21 @@
   "$schema": "http://json-schema.org/schema#",
   "$id": "https://github.com/w3c/reffy/blob/main/schemas/browserlib/extract-dfns.json",
 
+  "$defs": {
+    "heading": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["href", "title"],
+      "properties": {
+        "id": { "$ref": "../common.json#/$defs/id" },
+        "href": { "$ref": "../common.json#/$defs/url" },
+        "title": { "type": "string" },
+        "number": { "$ref": "../common.json#/$defs/headingNumber" },
+        "alternateIds": { "type": "array", "items": { "$ref": "../common.json#/$defs/id"} }
+      }
+    }
+  },
+
   "type": "array",
   "items": {
     "type": "object",
@@ -24,19 +39,14 @@
         "enum": [
           "property", "descriptor", "value", "type",
           "at-rule", "function", "selector",
-
           "namespace", "interface", "constructor", "method", "argument",
           "attribute", "callback", "dictionary", "dict-member", "enum",
           "enum-value", "exception", "const", "typedef", "stringifier",
           "serializer", "iterator", "maplike", "setlike", "extended-attribute",
           "event", "permission",
-
           "element", "element-state", "element-attr", "attr-value",
-
           "cddl-module", "cddl-type", "cddl-parameter", "cddl-key", "cddl-value",
-
           "scheme", "http-header",
-
           "grammar", "abstract-op", "dfn"
         ],
         "$comment": "Types taken from src/browserlib/extract-dfns.mjs"
@@ -52,21 +62,25 @@
       "informative": {
         "type": "boolean"
       },
-      "heading": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": ["href", "title"],
-        "properties": {
-          "id": { "$ref": "../common.json#/$defs/id" },
-          "href": { "$ref": "../common.json#/$defs/url" },
-          "title": { "type": "string" },
-          "number": { "$ref": "../common.json#/$defs/headingNumber" },
-          "alternateIds": { "type": "array", "items": { "$ref": "../common.json#/$defs/id"} }
-        }
-      },
+      "heading": { "$ref": "#/$defs/heading" },
       "definedIn": {
         "type": "string"
       },
+      "links": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "id", "href", "name"],
+          "properties": {
+            "type": { "type": "string", "enum": ["dev"] },
+            "id": { "$ref": "../common.json#/$defs/id" },
+            "name": { "type": "string" },
+            "href": { "$ref": "../common.json#/$defs/url" },
+            "heading": { "$ref": "#/$defs/heading" }
+          }
+        }
+      },
       "htmlProse": {
         "type": "string",
         "minLength": 1

package/schemas/postprocessing/css.json

@@ -100,7 +100,7 @@
         "required": ["name", "type"],
         "additionalProperties": false,
         "properties": {
-          "name": { "type": "string", "pattern": "^[a-zA-Z0-9-\\(\\)\\[\\]\\{\\}]+$" },
+          "name": { "type": "string", "pattern": "^[a-zA-Z0-9-\\+\\(\\)\\[\\]\\{\\}]+$" },
           "for": { "$ref": "#/$defs/scopes" },
           "href": { "$ref": "../common.json#/$defs/url" },
           "type": { "type": "string", "enum": ["type"] },

package/src/browserlib/extract-dfns.mjs

@@ -1,5 +1,6 @@
 import extractWebIdl from './extract-webidl.mjs';
 import informativeSelector from './informative-selector.mjs';
+import getAbsoluteUrl from './get-absolute-url.mjs';
 import {parse} from "../../node_modules/webidl2/index.js";
 /**
  * Extract definitions in the spec that follow the "Definitions data model":
@@ -276,7 +277,11 @@ function definitionMapper(el, idToHeading, usesDfnDataModel) {
     // Enclosing element under which the definition appears. Value can be one of
     // "dt", "pre", "table", "heading", "note", "example", or "prose" (last one
     // indicates that definition appears in the main body of the specification)
-    definedIn
+    definedIn,
+
+    // Important links that complement the definition
+    // (typically: anchors in "for web developers" sections)
+    links: []
   };
 
   // Extract a prose definition in HTML for the term, if available
@@ -322,14 +327,14 @@ export default function (spec, idToHeading = {}) {
     break;
   }
 
-  const definitions = [...document.querySelectorAll(definitionsSelector)];
-  const usesDfnDataModel = definitions.some(dfn =>
+  const dfnEls = [...document.querySelectorAll(definitionsSelector)];
+  const usesDfnDataModel = dfnEls.some(dfn =>
     dfn.hasAttribute('data-dfn-type') ||
     dfn.hasAttribute('data-dfn-for') ||
     dfn.hasAttribute('data-export') ||
     dfn.hasAttribute('data-noexport'));
 
-  return definitions
+  const definitions = dfnEls
     .map(node => {
       // 2021-06-21: Temporary preprocessing of invalid "idl" dfn type (used for
       // internal slots) while fix for https://github.com/w3c/respec/issues/3644
@@ -365,6 +370,45 @@ export default function (spec, idToHeading = {}) {
     })
     .map(node => definitionMapper(node, idToHeading, usesDfnDataModel))
     .filter(isNotAlreadyExported);
+
+  // Some specs have informative "For web developers" sections targeted at
+  // presenting concepts to web developers. These sections contain anchors
+  // that are useful for documentation purpose. The anchors themselves are
+  // references to terms defined elsewhere in the spec. We will capture them in
+  // a `links` property attached to the underlying definition.
+  // Note: Ideally, `.domintro` would be added to the informative selector list
+  // but some specs use `.domintro` for lists that define IDL terms. We'll get
+  // rid of them by skipping lists that have `dfn`.
+  const devSelector = '.domintro dt:not(dt:has(dfn)) a[id]';
+  for (const node of [...document.querySelectorAll(devSelector)]) {
+    const dfnHref = getAbsoluteUrl(node, { attribute: 'href' });
+    const dfn = definitions.find(d => d.href === dfnHref);
+    if (dfn) {
+      const href = getAbsoluteUrl(node);
+      const page = node.closest('[data-reffy-page]')?.getAttribute('data-reffy-page');
+      dfn.links.push({
+        type: 'dev',
+        id: node.getAttribute('id'),
+        name: normalize(node.closest('dt').textContent),
+        href,
+        heading: idToHeading[href] ?? {
+          href: (new URL(page ?? window.location.href)).toString(),
+          title: document.title
+        }
+      });
+    }
+    else {
+      // When an interface inherits from another, the reference may target
+      // a base dfn in another spec. For example:
+      // https://encoding.spec.whatwg.org/#ref-for-dom-generictransformstream-readable
+      // ... targets the Streams spec. There aren't many occurrences of this
+      // pattern and the occurrences do not look super interesting to link to
+      // from a documentation perspective. Let's skip them.
+      console.warn('[reffy]', `Dev dfn ${node.textContent} (${node.id}) targets unknown/external dfn at ${node.href}`);
+    }
+  }
+
+  return definitions;
 }
 
 function preProcessEcmascript() {
@@ -661,6 +705,21 @@ function preProcessEcmascript() {
       }
     });
 
+  // Extract production rules
+  [...document.querySelectorAll("emu-grammar[type=definition] emu-production")]
+    .forEach(el => {
+      const dfn = wrapWithDfn(el);
+      dfn.id = el.id;
+      dfn.dataset.lt = el.getAttribute("name");
+      dfn.dataset.dfnType = "grammar";
+      dfn.dataset.noexport = "";
+      if (el.closest('[data-reffy-page$="additional-ecmascript-features-for-web-browsers.html"]')) {
+        // Production rules in Annex B replace some of the production rules
+        // defined in other sections for web browser hosts.
+        dfn.dataset.dfnFor = "Web browsers";
+      }
+    });
+
   [...document.querySelectorAll("dfn")]
     .filter(legacySectionFilter)
     .forEach(el => {

package/src/browserlib/get-absolute-url.mjs

@@ -18,7 +18,12 @@ export default function (node, { singlePage, attribute } =
   const url = new URL(page ?? window.location.href);
   const hashid = node.getAttribute(attribute);
   if (hashid) {
-    url.hash = '#' + encodeURIComponent(hashid);
+    let fragment = hashid;
+    if (hashid.match(/^#/) && attribute === 'href') {
+      // Function is called to turn a fragment ref into an absolute URL
+      fragment = hashid.substring(1);
+    }
+    url.hash = '#' + encodeURIComponent(fragment);
   }
   return url.toString();
 }