Add crude dfns patching mechanism (#1159)

* Filter out dfns defined in an "exclude" IDL block

Trusted Types has this weird IDL block where it defines DOMParser but does not
seem to mean it:
https://w3c.github.io/trusted-types/dist/spec/#integration-with-dom-parsing

The IDL block has an `exclude` class and is thus ignored by the IDL extraction
logic. This update completes the dfns extraction logic to also ignore terms
defined in such an IDL block. This avoids ending up with duplicated terms.

* Add post-processing module to patch dfns

This creates a crude patching mechanism to patch dfns directly after crawling a
spec. This can be used to drop some well-known duplicates that cause referencing
issues.

The module needs to be maintained over time, so goal is to only hardcode rules
when really needed, e.g. because the re-definition of a term causes actual
referencing issues.

The module runs at the spec level for simplicity. A more complete version could
run at the crawl level, detect duplicates and try to act on them. That would
require investing more energy into it :)

src/browserlib/extract-dfns.mjs

@@ -260,6 +260,8 @@ export default function (spec, idToHeading = {}) {
       return node;
     })
     .filter(hasValidType)
+    // Exclude IDL terms defined in a block that is flagged as to be excluded
+    .filter(node => !node.closest('.exclude'))
     // When the whole term links to an external spec, the definition is an
     // imported definition. Such definitions are not "real" definitions, let's
     // skip them.

src/lib/post-processor.js

@@ -60,7 +60,8 @@ const modules = {
   events: require('../postprocessing/events'),
   idlnames: require('../postprocessing/idlnames'),
   idlparsed: require('../postprocessing/idlparsed'),
-  annotatelinks: require('../postprocessing/annotate-links')
+  annotatelinks: require('../postprocessing/annotate-links'),
+  patchdfns: require('../postprocessing/patch-dfns')
 };
 
 

src/postprocessing/patch-dfns.js

@@ -0,0 +1,40 @@
+/**
+ * Post-processing module that can be used to patch definition extracts,
+ * typically to drop problematic duplicate definitions they may contain.
+ * 
+ * This post-processing module should only be considered as last resort because
+ * it requires manual maintenance over time. Goal is to hardcode things here
+ * only when duplicate terms create actual referencing issues, not to resolve
+ * all duplicate definitions conflicts.
+ *
+ * The module runs at the spec level.
+ */
+
+module.exports = {
+  dependsOn: ['dfns'],
+  input: 'spec',
+  property: 'dfns',
+
+  run: async function (spec, options) {
+    // Note the spec object passed to post-processing modules does not contain
+    // any specific detail on the spec other than the crawled URL, so no direct
+    // way to match spec on its shortname
+    if (spec.crawled && spec.dfns) {
+      // https://github.com/w3c/webref/blob/main/ed/idlpatches/orientation-event.idl.patch
+      if (spec.crawled.includes('/deviceorientation/') ||
+          spec.crawled.includes('/TR/orientation-event/')) {
+        spec.dfns = spec.dfns.filter(dfn =>
+          !dfn.linkingText.includes('PermissionState') &&
+          !dfn.for.includes('PermissionState'));
+      }
+
+      // https://github.com/w3c/webref/blob/main/ed/idlpatches/portals.idl.patch
+      else if (spec.crawled.includes('/portals/')) {
+        spec.dfns = spec.dfns.filter(dfn =>
+          dfn.linkingText[0] !== 'MessageEventSource');
+      }
+    }
+
+    return spec;
+  }
+};