@webref/xref 1.0.1 → 1.2.0

package/ed/headings/webmcp.json

@@ -101,6 +101,20 @@
       "title": "Declarative WebMCP",
       "number": "4.3"
     },
+    {
+      "id": "events",
+      "href": "https://webmachinelearning.github.io/webmcp/#events",
+      "level": 3,
+      "title": "Events",
+      "number": "4.4"
+    },
+    {
+      "id": "permissions-policy",
+      "href": "https://webmachinelearning.github.io/webmcp/#permissions-policy",
+      "level": 3,
+      "title": "Permissions policy integration",
+      "number": "4.5"
+    },
     {
       "id": "interaction-with-agents",
       "href": "https://webmachinelearning.github.io/webmcp/#interaction-with-agents",

package/ed/headings/webusb.json

@@ -377,7 +377,7 @@
       "id": "informative",
       "href": "https://wicg.github.io/webusb/#informative",
       "level": 3,
-      "title": "Informative References"
+      "title": "Non-Normative References"
     },
     {
       "id": "idl-index",

package/ed/headings/webvtt1.json

@@ -17,8 +17,8 @@
       "title": "Abstract"
     },
     {
-      "id": "status",
-      "href": "https://w3c.github.io/webvtt/#status",
+      "id": "sotd",
+      "href": "https://w3c.github.io/webvtt/#sotd",
       "level": 2,
       "title": "Status of this document"
     },

package/index.js

@@ -9,7 +9,8 @@ const scriptPath = path.dirname(fileURLToPath(import.meta.url));
  */
 const xref = {
   dfns: [],
-  headings: []
+  headings: [],
+  specs: []
 };
 
 /**
@@ -63,7 +64,7 @@ function setupExtracts(type, rootFolder) {
         if (entry.alternateIds) {
           for (const id of entry.alternateIds) {
             const url = new URL(entry.href);
-            url.hash = id;
+            url.hash = encodeURIComponent(id);
             const href = url.toString();
             indexUrl(href, { source: 'headings', entry });
           }
@@ -83,6 +84,18 @@ export function setup(rootFolder = scriptPath) {
   if (initialized) {
     return;
   }
+  if (rootFolder === scriptPath) {
+    // We're in "package" mode, the root folder contains a `specs.json` file.
+    xref.specs = JSON.parse(fs.readFileSync(path.join(rootFolder, 'specs.json'), 'utf8'));
+  }
+  else {
+    // We're in "use crawl results" mode, the root folder won't contain a
+    // `specs.json` file, but the `ed` folder should have a crawl index with a
+    // list of specs.
+    const crawl = JSON.parse(fs.readFileSync(path.join(rootFolder, 'ed', 'index.json'), 'utf8'));
+    xref.specs = crawl.results;
+  }
+
   for (const type of ['dfns', 'headings']) {
     setupExtracts(type, rootFolder);
   }
@@ -94,14 +107,74 @@ export function setup(rootFolder = scriptPath) {
  * Lookup a URL in the loaded database
  *
  * The function returns an array of entries. Each entry is an object with a
- * `source` key set to "dfns", "headings", "links", or "alternateIds"; and a
- * `entry` key set to either a dfn object when `source` is "dfns" or "links",
- * or a heading object when `source` is "headings" or "alternateIds".
+ * `source` key set to "dfns" or "headings"; and a `entry` key set to either a
+ * dfn object when `source` is "dfns" or a heading object when `source` is
+ * "headings".
+ *
+ * The function accepts a lookup options object as second parameter that sets
+ * lookup capabilities and filters. Check the README for details.
  */
-export function lookup(url) {
+export function lookup(url, { standing, version, series } = {}) {
   if (!initialized) {
-    throw new Error('Cannot run lookup before the `setup()` function gets called');
+    throw new Error('The `lookup()` function was called before `setup()`.');
+  }
+  if (!url) {
+    throw new Error('The `lookup()` function was called without argument.');
+  }
+
+  // URL hashes in Webref extracts are percent-encoded. Goal is to support
+  // lookup of both percent-encoded and non percent-encoded URLs. To make sure
+  // that we end up with what we need, let's force a decode (this will be a
+  // no-op if the fragment is not percent-encoded) before we re-encode.
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(url);
+  }
+  catch (err) {
+    throw new Error('The `lookup()` function was called with an invalid URL.', err);
+  }
+  let decodedHash;
+  try {
+    decodedHash = decodeURIComponent(parsedUrl.hash);
+  }
+  catch {
+    decodedHash = parsedUrl.hash;
+  }
+  parsedUrl.hash = encodeURIComponent(decodedHash.replace(/^#/, ''));
+  let lookupUrl = parsedUrl.toString();
+
+  // If the series flag is set, the provided URL may also be a spec series URL,
+  // which we need to convert to the URL of the current spec in the series.
+  if (series && !urlIndex[lookupUrl.toString()]) {
+    // Drop the hash to match spec URLs
+    const hash = parsedUrl.hash;
+    parsedUrl.hash = '';
+    const specUrl = parsedUrl.toString();
+    const spec = xref.specs.find(spec =>
+      spec.shortname === spec.series.currentSpecification &&
+      (spec.series.nightlyUrl === specUrl || spec.series.releaseUrl === specUrl)
+    );
+    if (spec) {
+      // The lookup URL matches a series URL indeed, let's change it to the URL
+      // of the current spec in the series
+      const currentUrl = new URL(
+        (spec.series.nightlyUrl === specUrl) ? spec.nightly.url : spec.release.url
+      );
+      currentUrl.hash = hash;
+      lookupUrl = currentUrl.toString();
+    }
+  }
+
+  // Look for the resulting URL and filter results as needed
+  let res = urlIndex[lookupUrl.toString()] ?? [];
+  const hasSpecFilter = standing || version;
+  if (hasSpecFilter) {
+    res = res.filter(match => {
+      const entry = match.entry;
+      const spec = xref.specs.find(spec => spec.shortname === entry.spec);
+      return (!standing || spec.standing === standing) &&
+        (!version || entry.version === version);
+    });
   }
-  const res = urlIndex[url];
-  return structuredClone(res) ?? [];
+  return structuredClone(res);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@webref/xref",
   "description": "Definitions of the web platform for cross-references purpose",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/w3c/webref.git",