Lint: Add additional checks and improve HTML parsing

New checks:

- Validate that constraint table links from steps are reasonable.
- Validate that constraint tables use links not styles for params.

Improved checks:

- Make duplicate word detection case insensitive and match at
  start/end of lines.

Internal changes:

- Massage HTML to allow node-html-parser to handle tables.
- Improve output when matching at line boundaries.
- Comment checks with "Generic" or "WebNN".

Author: inexorabletash

Diff for: tools/lint.mjs

@@ -63,11 +63,20 @@ log(`loading generated HTML "${options.html}"...`);
 let file = await fs.readFile(options.html, 'utf8');
 
 log('massaging HTML...');
-// node-html-parser doesn't understand that DT and DD are mutually self-closing;
+// node-html-parser doesn't understand that some elements are mutually self-closing;
 // tweak the source using regex magic.
-file = file.replaceAll(
-    /(<(dt|dd)\b[^>]*>)(.*?)(?=<(:?dt|dd|\/dl)\b)/sg,
-    (_, opener, tag, content) => `${opener}${content}</${tag}>`);
+[{tags: ['dt', 'dd'], containers: ['dl']},
+ {tags: ['thead', 'tbody', 'tfoot'], containers: ['table']},
+ {tags: ['tr'], containers: ['thead', 'tbody', 'tfoot', 'table']},
+].forEach(({tags, containers}) => {
+  const re = new RegExp(
+    '(<(' + tags.join('|') + ')\\b[^>]*>)' +
+      '(.*?)' +
+      '(?=<(:?' + tags.join('|') + '|/(' + containers.join('|') + '))\\b)',
+    'sg');
+  file = file.replaceAll(
+    re, (_, opener, tag, content) => `${opener}${content}</${tag}>`);
+});
 
 log('parsing HTML...');
 const root = parse(file, {
@@ -102,13 +111,25 @@ function error(message) {
 
 function format(match) {
   const CONTEXT = 20;
-  const prefix = match.input.substring(match.index - CONTEXT, match.index)
+
+  let prefix = match.input.substring(match.index - CONTEXT, match.index)
                      .split(/\n/)
                      .pop();
-  const suffix = match.input.substr(match.index + match[0].length, CONTEXT)
+  let suffix = match.input.substr(match.index + match[0].length, CONTEXT)
                      .split(/\n/)
                      .shift();
-  return (prefix.length === CONTEXT ? '...' : '') + prefix + match[0] + suffix +
+  let infix = match[0];
+
+  if (infix.startsWith('\n')) {
+    prefix = '';
+    infix = infix.slice(1);
+  }
+  if (infix.endsWith('\n')) {
+    suffix = '';
+    infix = infix.slice(0, -1);
+  }
+
+  return (prefix.length === CONTEXT ? '...' : '') + prefix + infix + suffix +
       (suffix.length === CONTEXT ? '...' : '');
 }
 
@@ -128,22 +149,26 @@ const ALGORITHM_STEP_SELECTOR = '.algorithm li > p:not(.issue)';
 // * `text` - rendered text content
 // * `root.querySelectorAll()` - operate on DOM-like nodes
 
-// Look for merge markers
+// Checks are marked with one of these tags:
+// * [Generic] - could apply to any spec
+// * [WebNN] - very specific to the WebNN spec
+
+// [Generic] Look for merge markers
 for (const match of source.matchAll(/<{7}|>{7}|^={7}$/mg)) {
   error(`Merge conflict marker: ${format(match)}`);
 }
 
-// Look for residue of unterminated auto-links in rendered text
+// [Generic] Look for residue of unterminated auto-links in rendered text
 for (const match of text.matchAll(/({{|}}|\[=|=\])/g)) {
   error(`Unterminated autolink: ${format(match)}`);
 }
 
-// Look for duplicate words (in source, since [=realm=] |realm| is okay)
-for (const match of html.matchAll(/ (\w+) \1 /g)) {
+// [Generic] Look for duplicate words (in source, since [=realm=] |realm| is okay)
+for (const match of html.matchAll(/(?:^|\s)(\w+) \1(?:$|\s)/ig)) {
   error(`Duplicate word: ${format(match)}`);
 }
 
-// Verify IDL lines wrap to avoid horizontal scrollbars
+// [Generic] Verify IDL lines wrap to avoid horizontal scrollbars
 const MAX_IDL_WIDTH = 88;
 for (const idl of root.querySelectorAll('pre.idl')) {
   idl.innerText.split(/\n/).forEach(line => {
@@ -154,19 +179,19 @@ for (const idl of root.querySelectorAll('pre.idl')) {
   });
 }
 
-// Look for undesired punctuation
+// [WebNN] Look for undesired punctuation
 for (const match of text.matchAll(/(::|×|÷|∗|−)/g)) {
   error(`Bad punctuation: ${format(match)}`);
 }
 
-// Look for undesired entity usage
+// [WebNN] Look for undesired entity usage
 for (const match of source.matchAll(/&(\w+);/g)) {
   if (!['amp', 'lt', 'gt', 'quot'].includes(match[1])) {
     error(`Avoid entities: ${format(match)}`);
   }
 }
 
-// Look for undesired phrasing
+// [WebNN] Look for undesired phrasing
 for (const match of source.matchAll(/the (\[=.*?=\]) of (\|.*?\|)[^,]/g)) {
   error(`Prefer "x's y" to "y of x": ${format(match)}`);
 }
@@ -180,17 +205,17 @@ for (const match of text.matchAll(/\bthe \S+ argument\b/g)) {
   error(`Drop 'the' and 'argument': ${format(match)}`);
 }
 
-// Look for incorrect use of shape for an MLOperandDescriptor
+// [WebNN] Look for incorrect use of shape for an MLOperandDescriptor
 for (const match of source.matchAll(/(\|\w*desc\w*\|)'s \[=MLOperand\/shape=\]/ig)) {
   error(`Use ${match[1]}.{{MLOperandDescriptor/dimensions}} not shape: ${format(match)}`);
 }
 
-// Look for missing dict-member dfns
+// [Generic] Look for missing dict-member dfns
 for (const element of root.querySelectorAll('.idl dfn[data-dfn-type=dict-member]')) {
   error(`Dictionary member missing dfn: ${element.innerText}`);
 }
 
-// Look for suspicious stuff in algorithm steps
+// [WebNN] Look for suspicious stuff in algorithm steps
 for (const element of root.querySelectorAll(ALGORITHM_STEP_SELECTOR)) {
   // [] used for anything but indexing, slots, and refs
   // Exclude \w[ for indexing (e.g. shape[n])
@@ -205,7 +230,7 @@ for (const element of root.querySelectorAll(ALGORITHM_STEP_SELECTOR)) {
   }
 }
 
-// Ensure vars are method/algorithm arguments, or initialized correctly
+// [Generic] Ensure vars are method/algorithm arguments, or initialized correctly
 for (const algorithm of root.querySelectorAll('.algorithm')) {
   const vars = algorithm.querySelectorAll('var');
   const seen = new Set();
@@ -253,17 +278,17 @@ for (const algorithm of root.querySelectorAll('.algorithm')) {
   }
 }
 
-// Eschew vars outside of algorithms.
+// [Generic] Eschew vars outside of algorithms.
 const algorithmVars = new Set(root.querySelectorAll('.algorithm var'));
 for (const v of root.querySelectorAll('var').filter(v => !algorithmVars.has(v))) {
   error(`Variable outside of algorithm: ${v.innerText}`);
 }
 
-
-// Prevent accidental normative references to other specs. This reports an error
-// if there is a normative reference to any spec *other* than these ones. This
-// helps avoid an autolink like [=object=] adding an unexpected reference to
-// [FILEAPI]. Add to this list if a new normative reference is intended.
+// [WebNN] Prevent accidental normative references to other specs. This reports
+// an error if there is a normative reference to any spec *other* than these
+// ones. This helps avoid an autolink like [=object=] adding an unexpected
+// reference to [FILEAPI]. Add to this list if a new normative reference is
+// intended.
 const NORMATIVE_REFERENCES = new Set([
   '[ECMASCRIPT]',
   '[HTML]',
@@ -282,7 +307,7 @@ for (const term of root.querySelectorAll('#normative + dl > dt')) {
   }
 }
 
-// Detect syntax errors in JS.
+// [Generic] Detect syntax errors in JS.
 for (const pre of root.querySelectorAll('pre.highlight:not(.idl)')) {
   const script = pre.innerText.replaceAll(/&amp;/g, '&')
                      .replaceAll(/&lt;/g, '<')
@@ -294,20 +319,20 @@ for (const pre of root.querySelectorAll('pre.highlight:not(.idl)')) {
   }
 }
 
-// Ensure algorithm steps end in '.' or ':'.
+// [Generic] Ensure algorithm steps end in '.' or ':'.
 for (const p of root.querySelectorAll(ALGORITHM_STEP_SELECTOR)) {
   const match = p.innerText.match(/[^.:]$/);
   if (match) {
     error(`Algorithm steps should end with '.' or ':': ${format(match)}`);
   }
 }
 
-// Avoid incorrect links to list/empty.
+// [Generic] Avoid incorrect links to list/empty.
 for (const match of source.matchAll(/is( not)? \[=(list\/|stack\/|queue\/|)empty=\]/g)) {
   error(`Link to 'is empty' (adjective) not 'empty' (verb): ${format(match)}`);
 }
 
-// Ensure every method dfn is correctly associated with an interface.
+// [Generic] Ensure every method dfn is correctly associated with an interface.
 const interfaces = new Set(
   root.querySelectorAll('dfn[data-dfn-type=interface]').map(e => e.innerText));
 for (const dfn of root.querySelectorAll('dfn[data-dfn-type=method]')) {
@@ -317,13 +342,13 @@ for (const dfn of root.querySelectorAll('dfn[data-dfn-type=method]')) {
   }
 }
 
-// Ensure every IDL argument is linked to a definition.
+// [Generic] Ensure every IDL argument is linked to a definition.
 for (const dfn of root.querySelectorAll('pre.idl dfn[data-dfn-type=argument]')) {
   const dfnFor = dfn.getAttribute('data-dfn-for');
   error(`Missing <dfn argument for="${dfnFor}">${dfn.innerText}</dfn> (or equivalent)`);
 }
 
-// Ensure every argument dfn is correctly associated with a method.
+// [Generic] Ensure every argument dfn is correctly associated with a method.
 // This tries to catch extraneous definitions, e.g. after an arg is removed.
 for (const dfn of root.querySelectorAll('dfn[data-dfn-type=argument]')) {
   const dfnFor = dfn.getAttribute('data-dfn-for');
@@ -332,8 +357,9 @@ for (const dfn of root.querySelectorAll('dfn[data-dfn-type=argument]')) {
   }
 }
 
-// Try to catch type mismatches like |tensor|.{{MLGraph/...}}. Note that the
-// test is keyed on the variable name; variables listed here are not validated.
+// [WebNN] Try to catch type mismatches like |tensor|.{{MLGraph/...}}. Note that
+// the test is keyed on the variable name; variables listed here are not
+// validated.
 for (const match of source.matchAll(/\|(\w+)\|\.{{(\w+)\/.*?}}/g)) {
   const [_, v, i] = match;
   [['MLTensor', ['tensor']],
@@ -351,13 +377,42 @@ for (const match of source.matchAll(/\|(\w+)\|\.{{(\w+)\/.*?}}/g)) {
   });
 }
 
+// [WebNN] Verify that linked constraints table IDs are reasonable. Bikeshed
+// will flag any broken links; this just tries to ensure that links within the
+// algorithm go to that algorithm's associated table.
+for (const algorithm of root.querySelectorAll(
+       '.algorithm[data-algorithm-for=MLGraphBuilder]')) {
+  const name = algorithm.getAttribute('data-algorithm');
+  if (name.match(/^(\w+)\(/)) {
+    const method = RegExp.$1;
+    for (const href of algorithm.querySelectorAll('a')
+           .map(a => a.getAttribute('href'))
+               .filter(href => href.match(/#constraints-/))) {
+      // Allow either exact case or lowercase match for table ID.
+      if (
+        href !== '#constraints-' + method &&
+        href !== '#constraints-' + method.toLowerCase()) {
+        error(`Steps for ${method}() link to ${href}`);
+      }
+    }
+  }
+}
+
+// [WebNN] Ensure constraints tables use linking not styling
+for (const table of root.querySelectorAll('table.data').filter(e => e.id.startsWith('constraints-'))) {
+  for (const match of table.innerHTML.matchAll(/<em>(?!output)(\w+)<\/em>/ig)) {
+    error(`Constraints table should link not style args: ${format(match)}`);
+  }
+}
+
 // TODO: Generate this from the IDL itself.
 const dictionaryTypes = ['MLOperandDescriptor', 'MLContextLostInfo'];
 
-// Ensure JS objects are created with explicit realm
+// [Generic] Ensure JS objects are created with explicit realm
 for (const match of text.matchAll(/ a new promise\b(?! in realm)/g)) {
   error(`Promise creation must specify realm: ${format(match)}`);
 }
+// [Generic] Ensure JS objects are created with explicit realm
 for (const match of text.matchAll(/ be a new ([A-Z]\w+)\b(?! in realm)/g)) {
   const type = match[1];
   // Dictionaries are just maps, so they don't need a realm.