add lint for header format

src/lint/collect-header-diagnostics.ts

@@ -0,0 +1,104 @@
+import type { LintingError } from './algorithm-error-reporter-type';
+
+import { getLocation } from './utils';
+
+const ruleId = 'header-format';
+
+export function collectHeaderDiagnostics(
+  dom: any,
+  headers: { element: Element; contents: string }[]
+) {
+  let lintingErrors: LintingError[] = [];
+
+  for (let { element, contents } of headers) {
+    if (!/\(.*\)$/.test(contents) || / Operator \( `[^`]+` \)$/.test(contents)) {
+      continue;
+    }
+
+    function indexToLineAndColumn(index: number) {
+      let headerLines = contents.split('\n');
+      let headerLine = 0;
+      let seen = 0;
+      while (true) {
+        if (seen + headerLines[headerLine].length >= index) {
+          break;
+        }
+        seen += headerLines[headerLine].length + 1; // +1 for the '\n'
+        ++headerLine;
+      }
+      let headerColumn = index - seen;
+
+      let elementLoc = getLocation(dom, element);
+      let line = elementLoc.startTag.line + headerLine;
+      let column =
+        headerLine === 0
+          ? elementLoc.startTag.col +
+            (elementLoc.startTag.endOffset - elementLoc.startTag.startOffset) +
+            headerColumn
+          : headerColumn + 1;
+
+      return { line, column };
+    }
+
+    let name = contents.substring(0, contents.indexOf('('));
+    let params = contents.substring(contents.indexOf('(') + 1, contents.length - 1);
+
+    if (/ $/.test(name)) {
+      name = name.substring(0, name.length - 1);
+    } else {
+      let { line, column } = indexToLineAndColumn(name.length);
+      lintingErrors.push({
+        ruleId,
+        nodeType: 'H1',
+        line,
+        column,
+        message: 'expected header to have a space before the argument list',
+      });
+    }
+
+    let nameMatches = [
+      /^(Runtime|Static) Semantics: [A-Z][A-Za-z0-9/]*$/,
+      /^(Number|BigInt)::[a-z][A-Za-z0-9]*$/,
+      /^\[\[[A-Z][A-Za-z0-9]*\]\]$/,
+      /^_[A-Z][A-Za-z0-9]*_$/,
+      /^[A-Za-z][A-Za-z0-9]*(\.[A-Za-z][A-Za-z0-9]*)*( \[ @@[a-z][a-zA-Z]+ \])?$/,
+      /^%[A-Z][A-Za-z0-9]*%(\.[A-Za-z][A-Za-z0-9]*)*( \[ @@[a-z][a-zA-Z]+ \])?$/,
+    ].some(r => r.test(name));
+
+    if (!nameMatches) {
+      let { line, column } = indexToLineAndColumn(0);
+      lintingErrors.push({
+        ruleId,
+        nodeType: 'H1',
+        line,
+        column,
+        message: `expected operation to have a name like 'Example', 'Runtime Semantics: Foo', 'Example.prop', etc, but found ${JSON.stringify(
+          name
+        )}`,
+      });
+    }
+
+    let paramsMatches =
+      params.match(/\[/g)?.length === params.match(/\]/g)?.length &&
+      [
+        /^ $/,
+        /^ \. \. \. $/,
+        /^ (_[A-Za-z0-9]+_, )*\.\.\._[A-Za-z0-9]+_ $/,
+        /^ (_[A-Za-z0-9]+_, )*… (, _[A-Za-z0-9]+_)+ $/,
+        /^ (\[ )?_[A-Za-z0-9]+_(, _[A-Za-z0-9]+_)*( \[ , _[A-Za-z0-9]+_(, _[A-Za-z0-9]+_)*)*( \])* $/,
+      ].some(r => r.test(params));
+
+    if (!paramsMatches) {
+      let { line, column } = indexToLineAndColumn(name.length + 1);
+      lintingErrors.push({
+        ruleId,
+        nodeType: 'H1',
+        line,
+        column,
+        message: `expected parameter list to look like '( _a_, [ , _b_ ] )', '( _foo_, _bar_, ..._baz_ )', '( _foo_, … , _bar_ )', or '( . . . )'`,
+      });
+    }
+  }
+
+  return lintingErrors;
+}

src/lint/collect-nodes.ts

@@ -3,6 +3,7 @@ import type { Node as EcmarkdownNode } from 'ecmarkdown';
 import { getLocation } from './utils';
 
 export function collectNodes(sourceText: string, dom: any, document: Document) {
+  let headers: { element: Element; contents: string }[] = [];
   let mainGrammar: { element: Element; source: string }[] = [];
   let sdos: { grammar: Element; alg: Element }[] = [];
   let earlyErrors: { grammar: Element; lists: HTMLUListElement[] }[] = [];
@@ -28,6 +29,7 @@ export function collectNodes(sourceText: string, dom: any, document: Document) {
         let first = node.firstElementChild;
         if (first !== null && first.nodeName === 'H1') {
           let title = first.textContent ?? '';
+          headers.push({ element: first, contents: title });
           if (title.trim() === 'Static Semantics: Early Errors') {
             let grammar = null;
             let lists: HTMLUListElement[] = [];
@@ -101,5 +103,5 @@ export function collectNodes(sourceText: string, dom: any, document: Document) {
   }
   visitCurrentNode();
 
-  return { mainGrammar, sdos, earlyErrors, algorithms };
+  return { mainGrammar, headers, sdos, earlyErrors, algorithms };
 }

src/lint/lint.ts

@@ -3,6 +3,7 @@ import { emit } from 'ecmarkdown';
 import { collectNodes } from './collect-nodes';
 import { collectGrammarDiagnostics } from './collect-grammar-diagnostics';
 import { collectAlgorithmDiagnostics } from './collect-algorithm-diagnostics';
+import { collectHeaderDiagnostics } from './collect-header-diagnostics';
 import type { Reporter } from './algorithm-error-reporter-type';
 
 /*
@@ -16,7 +17,11 @@ There's more to do:
 https://github.com/tc39/ecmarkup/issues/173
 */
 export function lint(report: Reporter, sourceText: string, dom: any, document: Document) {
-  let { mainGrammar, sdos, earlyErrors, algorithms } = collectNodes(sourceText, dom, document);
+  let { mainGrammar, headers, sdos, earlyErrors, algorithms } = collectNodes(
+    sourceText,
+    dom,
+    document
+  );
 
   let { grammar, oneOffGrammars, lintingErrors } = collectGrammarDiagnostics(
     dom,
@@ -28,6 +33,8 @@ export function lint(report: Reporter, sourceText: string, dom: any, document: D
 
   lintingErrors.push(...collectAlgorithmDiagnostics(dom, sourceText, algorithms));
 
+  lintingErrors.push(...collectHeaderDiagnostics(dom, headers));
+
   if (lintingErrors.length > 0) {
     report(lintingErrors, sourceText);
     return;

test/lint.js

@@ -1,6 +1,6 @@
 'use strict';
 
-let { assertLint, positioned, lintLocationMarker: M } = require('./lint-helpers');
+let { assertLint, assertLintFree, positioned, lintLocationMarker: M } = require('./lint-helpers');
 
 describe('linting whole program', function () {
   describe('grammar validity', function () {
@@ -110,4 +110,102 @@ describe('linting whole program', function () {
       );
     });
   });
+
+  describe('header format', function () {
+    it('name format', async function () {
+      await assertLint(
+        positioned`
+          <emu-clause id="foo">
+            <h1>${M}something: ( )</h1>
+        `,
+        {
+          ruleId: 'header-format',
+          nodeType: 'H1',
+          message:
+            "expected operation to have a name like 'Example', 'Runtime Semantics: Foo', 'Example.prop', etc, but found \"something:\"",
+        }
+      );
+    });
+
+    it('spacing', async function () {
+      await assertLint(
+        positioned`
+          <emu-clause id="foo">
+            <h1>Example${M}( )</h1>
+        `,
+        {
+          ruleId: 'header-format',
+          nodeType: 'H1',
+          message: 'expected header to have a space before the argument list',
+        }
+      );
+    });
+
+    it('arg format', async function () {
+      await assertLint(
+        positioned`
+          <emu-clause id="foo">
+            <h1>Example ${M}(_a_)</h1>
+        `,
+        {
+          ruleId: 'header-format',
+          nodeType: 'H1',
+          message:
+            "expected parameter list to look like '( _a_, [ , _b_ ] )', '( _foo_, _bar_, ..._baz_ )', '( _foo_, … , _bar_ )', or '( . . . )'",
+        }
+      );
+    });
+
+    it('legal names', async function () {
+      await assertLintFree(`
+          <emu-clause id="foo">
+            <h1>Example ( )</h1>
+          </emu-clause>
+          <emu-clause id="foo">
+            <h1>Runtime Semantics: Example ( )</h1>
+          </emu-clause>
+          <emu-clause id="foo">
+            <h1>The * Operator ( \`*\` )</h1>
+          </emu-clause>
+          <emu-clause id="foo">
+            <h1>Number::example ( )</h1>
+          </emu-clause>
+          <emu-clause id="foo">
+            <h1>[[Example]] ( )</h1>
+          </emu-clause>
+          <emu-clause id="foo">
+            <h1>_Example_ ( )</h1>
+          </emu-clause>
+          <emu-clause id="foo">
+            <h1>%Foo%.bar [ @@iterator ] ( )</h1>
+          </emu-clause>
+      `);
+    });
+
+    it('legal argument lists', async function () {
+      await assertLintFree(`
+          <emu-clause id="foo">
+            <h1>Example ( )</h1>
+          </emu-clause>
+          <emu-clause id="foo">
+            <h1>Example ( _foo_ )</h1>
+          </emu-clause>
+          <emu-clause id="foo">
+            <h1>Example ( [ _foo_ ] )</h1>
+          </emu-clause>
+          <emu-clause id="foo">
+            <h1>Date ( _year_, _month_ [ , _date_ [ , _hours_ [ , _minutes_ [ , _seconds_ [ , _ms_ ] ] ] ] ] )</h1>
+          </emu-clause>
+          <emu-clause id="foo">
+            <h1>Object ( . . . )</h1>
+          </emu-clause>
+          <emu-clause id="foo">
+            <h1>String.raw ( _template_, ..._substitutions_ )</h1>
+          </emu-clause>
+          <emu-clause id="foo">
+            <h1>Function ( _p1_, _p2_, &hellip; , _pn_, _body_ )</h1>
+          </emu-clause>
+      `);
+    });
+  });
 });