Fix header parser (#403)

Author: bakkot

src/Clause.ts

@@ -7,6 +7,14 @@ import type { Context } from './Context';
 import Builder from './Builder';
 import { formatPreamble, parseStructuredHeaderDl, parseAndFormatH1 } from './header-parser';
 
+export function extractStructuredHeader(header: Element): Element | null {
+  const dl = header.nextElementSibling;
+  if (dl == null || dl.tagName !== 'DL' || !dl.classList.contains('header')) {
+    return null;
+  }
+  return dl;
+}
+
 /*@internal*/
 export default class Clause extends Builder {
   id: string;
@@ -93,8 +101,8 @@ export default class Clause extends Builder {
   }
 
   buildStructuredHeader(header: Element) {
-    const dl = header.nextElementSibling;
-    if (dl == null || dl.tagName !== 'DL' || !dl.classList.contains('header')) {
+    const dl = extractStructuredHeader(header);
+    if (dl === null) {
       return;
     }
     // if we find such a DL, treat this as a structured header

src/header-parser.ts

@@ -306,7 +306,6 @@ export function parseAndFormatH1(
   }
 
   const {
-    type,
     wrappingTag,
     prefix,
     name,
@@ -338,19 +337,14 @@ export function parseAndFormatH1(
     }
   }
 
-  let formattedHeader;
-  if (type === 'single-line') {
-    formattedHeader = header.innerHTML;
-  } else {
-    formattedHeader =
-      (prefix == null ? '' : prefix + ' ') +
-      name +
-      ' ' +
-      printSimpleParamList(params, optionalParams);
+  let formattedHeader =
+    (prefix == null ? '' : prefix + ' ') +
+    name +
+    ' ' +
+    printSimpleParamList(params, optionalParams);
 
-    if (wrappingTag !== null) {
-      formattedHeader = `<${wrappingTag}>${formattedHeader}</${wrappingTag}>`;
-    }
+  if (wrappingTag !== null) {
+    formattedHeader = `<${wrappingTag}>${formattedHeader}</${wrappingTag}>`;
   }
 
   return { name, formattedHeader, formattedParams, formattedReturnType: returnType };

src/lint/collect-header-diagnostics.ts

@@ -1,3 +1,4 @@
+import { extractStructuredHeader } from '../Clause';
 import type { Warning } from '../Spec';
 
 import { offsetToLineAndColumn } from '../utils';
@@ -9,6 +10,10 @@ export function collectHeaderDiagnostics(
   headers: { element: Element; contents: string }[]
 ) {
   for (const { element, contents } of headers) {
+    if (extractStructuredHeader(element) !== null) {
+      // these will be handled by header-parser.ts
+      continue;
+    }
     if (!/\(.*\)$/.test(contents) || / Operator \( `[^`]+` \)$/.test(contents)) {
       continue;
     }

test/baselines/generated-reference/effect-user-code.html

@@ -27,61 +27,61 @@ <h1><span class="secnum">3</span> Nop ( )</h1>
 </emu-clause>
 
 <emu-clause id="sec-direct-call" type="abstract operation" aoid="DirectCall">
-  <h1><span class="secnum">4</span> DirectCall()</h1>
+  <h1><span class="secnum">4</span> DirectCall ( )</h1>
   <p>The abstract operation DirectCall takes no arguments. Calling AOs that can call user code should insert <code>e-user-code</code> as a class into the AO link. It performs the following steps when called:</p>
   <emu-alg><ol><li><emu-xref aoid="UserCode" id="_ref_0"><a href="#sec-user-code" class="e-user-code">UserCode</a></emu-xref>().</li><li><emu-xref aoid="UserCode2" id="_ref_1"><a href="#sec-user-code-2" class="e-user-code">UserCode2</a></emu-xref>().</li></ol></emu-alg>
 </emu-clause>
 
 <emu-clause id="sec-transitive-call" type="abstract operation" aoid="TransitiveCall">
-  <h1><span class="secnum">5</span> TransitiveCall()</h1>
+  <h1><span class="secnum">5</span> TransitiveCall ( )</h1>
   <p>The abstract operation TransitiveCall takes no arguments. Calling AOs that can transitively call user code should insert <code>e-user-code</code> as a class into the AO link. It performs the following steps when called:</p>
   <emu-alg><ol><li><emu-xref aoid="DirectCall" id="_ref_2"><a href="#sec-direct-call" class="e-user-code">DirectCall</a></emu-xref>().</li></ol></emu-alg>
 </emu-clause>
 
 <emu-clause id="sec-suppressed-direct-call" type="abstract operation" aoid="SuppressedDirectCall">
-  <h1><span class="secnum">6</span> SuppressedDirectCall()</h1>
+  <h1><span class="secnum">6</span> SuppressedDirectCall ( )</h1>
   <p>The abstract operation SuppressedDirectCall takes no arguments. Can-call-user-code callsites that are suppressed do not get <code>e-user-code</code> as a class in the AO link. It performs the following steps when called:</p>
   <emu-alg><ol><li><emu-xref aoid="TransitiveCall" id="_ref_3"><a href="#sec-transitive-call">TransitiveCall</a></emu-xref>().</li></ol></emu-alg>
 </emu-clause>
 
 <emu-clause id="sec-suppressed-transitive-call" type="abstract operation" aoid="SuppressedTransitiveCall">
-  <h1><span class="secnum">7</span> SuppressedTransitiveCall()</h1>
+  <h1><span class="secnum">7</span> SuppressedTransitiveCall ( )</h1>
   <p>The abstract operation SuppressedTransitiveCall takes no arguments. Can-call-user-code callsites that are suppressed do not propagate the effect It performs the following steps when called:</p>
   <emu-alg><ol><li><emu-xref aoid="SuppressedDirectCall" id="_ref_4"><a href="#sec-suppressed-direct-call">SuppressedDirectCall</a></emu-xref>().</li></ol></emu-alg>
 </emu-clause>
 
 <emu-clause id="sec-added-direct-call" type="abstract operation" aoid="AddedDirectCall">
-  <h1><span class="secnum">8</span> AddedDirectCall()</h1>
+  <h1><span class="secnum">8</span> AddedDirectCall ( )</h1>
   <p>The abstract operation AddedDirectCall takes no arguments. AOs can have manually added user-code effect at a callsite that propagates. It performs the following steps when called:</p>
   <emu-alg><ol><li><emu-xref aoid="Nop" id="_ref_5"><a href="#sec-nop" class="e-user-code">Nop</a></emu-xref>().</li></ol></emu-alg>
 </emu-clause>
 
 <emu-clause id="sec-added-transitive-call" type="abstract operation" aoid="AddedTransitiveCall">
-  <h1><span class="secnum">9</span> AddedTransitiveCall()</h1>
+  <h1><span class="secnum">9</span> AddedTransitiveCall ( )</h1>
   <p>The abstract operation AddedTransitiveCall takes no arguments. AOs can have manually added user-code effect at a callsite that propagates. It performs the following steps when called:</p>
   <emu-alg><ol><li><emu-xref aoid="AddedDirectCall" id="_ref_6"><a href="#sec-added-direct-call" class="e-user-code">AddedDirectCall</a></emu-xref>().</li></ol></emu-alg>
 </emu-clause>
 
 <emu-clause id="sec-sdo-invocation" type="abstract operation" aoid="SDOInvocations">
-  <h1><span class="secnum">10</span> SDOInvocations()</h1>
+  <h1><span class="secnum">10</span> SDOInvocations ( )</h1>
   <p>The abstract operation SDOInvocations takes no arguments. SDO-style invocations of AOs that can call user code also have the <code>e-user-code</code> class in the link. It performs the following steps when called:</p>
   <emu-alg><ol><li><emu-xref aoid="UserCode" id="_ref_7"><a href="#sec-user-code" class="e-user-code">UserCode</a></emu-xref> of Bar.</li></ol></emu-alg>
 </emu-clause>
 
 <emu-clause id="sec-non-invocations" type="abstract operation" aoid="NonInvocations">
-  <h1><span class="secnum">11</span> NonInvocations()</h1>
+  <h1><span class="secnum">11</span> NonInvocations ( )</h1>
   <p>The abstract operation NonInvocations takes no arguments. Non-invocations (i.e. not followed by () or " of") do not have <code>e-user-code</code> as a class in the AO link. It performs the following steps when called:</p>
   <emu-alg><ol><li><emu-xref aoid="UserCode" id="_ref_8"><a href="#sec-user-code">UserCode</a></emu-xref> is an abstract operation.</li></ol></emu-alg>
 </emu-clause>
 
 <emu-clause id="sec-non-abrupt" type="abstract operation" aoid="NonAbrupt">
-  <h1><span class="secnum">12</span> NonAbrupt()</h1>
+  <h1><span class="secnum">12</span> NonAbrupt ( )</h1>
   <p>The abstract operation NonAbrupt takes no arguments. Invocations that cannot result in abrupt completions suppress the user-code effect by default. It performs the following steps when called:</p>
   <emu-alg><ol><li>Let <var>res</var> be !&nbsp;<emu-xref aoid="UserCode" id="_ref_9"><a href="#sec-user-code">UserCode</a></emu-xref>().</li></ol></emu-alg>
 </emu-clause>
 
 <emu-clause id="sec-non-abrupt-override" type="abstract operation" aoid="NonAbruptOverride">
-  <h1><span class="secnum">13</span> NonAbruptOverride()</h1>
+  <h1><span class="secnum">13</span> NonAbruptOverride ( )</h1>
   <p>The abstract operation NonAbruptOverride takes no arguments. Invocations that cannot result in abrupt completions suppress the user-code effect by default but can still be overridden. It performs the following steps when called:</p>
   <emu-alg><ol><li>Let <var>res</var> be !&nbsp;<emu-xref aoid="UserCode" id="_ref_10"><a href="#sec-user-code" class="e-user-code e-user-code">UserCode</a></emu-xref>().</li></ol></emu-alg>
 </emu-clause>
@@ -99,43 +99,43 @@ <h1><span class="secnum">15</span> Static Semantics: StaticTransitiveCall</h1>
 </emu-clause>
 
 <emu-clause id="sec-rendered-meta" type="abstract operation" aoid="RenderedMeta">
-  <h1><span class="secnum">16</span> RenderedMeta()</h1>
+  <h1><span class="secnum">16</span> RenderedMeta ( )</h1>
   <p>The abstract operation RenderedMeta takes no arguments. emu-meta tags with the effects attribute that aren't surrounding what ecmarkup recognizes as invocations are changed into span tags to be rendered. The effects list is prefixed with e- and changed into class names. It performs the following steps when called:</p>
   <emu-alg><ol><li>Perform ?&nbsp;<span class="e-user-code"><var>O</var>.[[Call]]()</span>.</li></ol></emu-alg>
 </emu-clause>
 
 <emu-clause id="sec-make-abstract-closure" type="abstract operation" aoid="MakeAbstractClosure">
-  <h1><span class="secnum">17</span> MakeAbstractClosure()</h1>
+  <h1><span class="secnum">17</span> MakeAbstractClosure ( )</h1>
   <p>The abstract operation MakeAbstractClosure takes no arguments. The user-code effect doesn't propagate through Abstract Closure boundaries by recognizing the "be a new Abstract Closure" substring. It performs the following steps when called:</p>
   <emu-alg><ol><li>Let <var>closure</var> be a new Abstract Closure that captures nothing and performs the following steps when called:<ol><li><emu-xref aoid="UserCode" id="_ref_13"><a href="#sec-user-code" class="e-user-code">UserCode</a></emu-xref>().</li></ol></li><li>Return <var>closure</var>.</li></ol></emu-alg>
 </emu-clause>
 
 <emu-clause id="sec-call-make-abstract-closure" type="abstract operation" aoid="CallMakeAbstractClosure">
-  <h1><span class="secnum">18</span> CallMakeAbstractClosure()</h1>
+  <h1><span class="secnum">18</span> CallMakeAbstractClosure ( )</h1>
   <p>The abstract operation CallMakeAbstractClosure takes no arguments. The user-code effect doesn't propagate through Abstract Closure boundaries by recognizing the "be a new Abstract Closure" substring. It performs the following steps when called:</p>
   <emu-alg><ol><li><emu-xref aoid="MakeAbstractClosure" id="_ref_14"><a href="#sec-make-abstract-closure">MakeAbstractClosure</a></emu-xref>().</li></ol></emu-alg>
 </emu-clause>
 
 <emu-clause id="sec-xref-not-first-child-of-emu-meta" type="abstract operation" aoid="XrefNotFirstChildOfEmuMeta">
-  <h1><span class="secnum">19</span> XrefNotFirstChildOfEmuMeta()</h1>
+  <h1><span class="secnum">19</span> XrefNotFirstChildOfEmuMeta ( )</h1>
   <p>The abstract operation XrefNotFirstChildOfEmuMeta takes no arguments. Effect additions and suppressions via emu-meta only affect xrefs that are the first child of the emu-meta. Below, <emu-xref aoid="UserCode" id="_ref_15"><a href="#sec-user-code" class="e-user-code">UserCode</a></emu-xref>() gets autolinked and get an xref. Its parent element is an emu-meta, but since the xref is not the first child, it should not be interpreted to override the effects of the <emu-xref aoid="UserCode" id="_ref_16"><a href="#sec-user-code" class="e-user-code">UserCode</a></emu-xref>() call. It performs the following steps when called:</p>
   <emu-alg><ol><li>Perform <span class="e-user-code"><var>map</var>.[[DefineOwnProperty]](! <emu-xref aoid="UserCode" id="_ref_17"><a href="#sec-user-code">UserCode</a></emu-xref>())</span>.</li></ol></emu-alg>
 </emu-clause>
 
 <emu-clause id="sec-result-of-evaluating" type="abstract operation" aoid="ResultOfEvaluating">
-  <h1><span class="secnum">20</span> ResultOfEvaluating()</h1>
+  <h1><span class="secnum">20</span> ResultOfEvaluating ( )</h1>
   <p>The abstract operation ResultOfEvaluating takes no arguments. The phrase "the result of evaluating Foo" is automatically considered as can call user code. It performs the following steps when called:</p>
   <emu-alg><ol><li>Let <var>res</var> be the result of <span class="e-user-code">evaluating <emu-nt>Foo</emu-nt></span>.</li></ol></emu-alg>
 </emu-clause>
 
 <emu-clause id="sec-fenced-effects" type="abstract operation" aoid="FencedEffects">
-  <h1><span class="secnum">21</span> FencedEffects()</h1>
+  <h1><span class="secnum">21</span> FencedEffects ( )</h1>
   <p>The abstract operation FencedEffects takes no arguments. Effects don't propagate past fences in parent steps. A fence must be at the beginning of a step. It performs the following steps when called:</p>
   <emu-alg><ol><li fence-effects="user-code">Fence.<ol><li><emu-xref aoid="UserCode" id="_ref_18"><a href="#sec-user-code" class="e-user-code">UserCode</a></emu-xref>().</li><li>Let <var>foo</var> be the result of <span class="e-user-code">evaluating <var>someUserCode</var></span>.</li></ol></li></ol></emu-alg>
 </emu-clause>
 
 <emu-clause id="sec-call-fenced-effects" type="abstract operation" aoid="CallFencedEffects">
-  <h1><span class="secnum">22</span> CallFencedEffects()</h1>
+  <h1><span class="secnum">22</span> CallFencedEffects ( )</h1>
   <p>The abstract operation CallFencedEffects takes no arguments. Effects don't propagate past fences in parent steps. It performs the following steps when called:</p>
   <emu-alg><ol><li><emu-xref aoid="FencedEffects" id="_ref_19"><a href="#sec-fenced-effects">FencedEffects</a></emu-xref>().</li></ol></emu-alg>
 </emu-clause>

test/baselines/generated-reference/structured-headers.html

@@ -71,4 +71,10 @@ <h1><span class="secnum">5</span> ExampleAO3 ( param )</h1>
   <p>The abstract operation <emu-xref aoid="ExampleAO3" id="_ref_0"><a href="#sec-example-return-type">ExampleAO3</a></emu-xref> takes argument param (an <emu-xref href="#integer"><a href="https://tc39.es/ecma262/#integer">integer</a></emu-xref>) and returns the return type. It performs the following steps when called:</p>
   <emu-alg><ol><li>Algorithm steps go here.</li></ol></emu-alg>
 </emu-clause>
+
+<emu-clause id="sec-example-single-line-return-type" type="abstract operation" aoid="ExampleA4">
+  <h1><span class="secnum">6</span> ExampleA4 ( )</h1>
+  <p>The abstract operation ExampleA4 takes no arguments and returns <emu-val>false</emu-val>. It performs the following steps when called:</p>
+  <emu-alg><ol><li>Return <emu-val>false</emu-val>.</li></ol></emu-alg>
+</emu-clause>
 </div></body>

test/baselines/sources/structured-headers.html

@@ -102,3 +102,12 @@ <h1>
     1. Algorithm steps go here.
   </emu-alg>
 </emu-clause>
+
+<emu-clause id="sec-example-single-line-return-type" type="abstract operation">
+  <h1>ExampleA4 ( ): *false*</h1>
+  <dl class='header'>
+  </dl>
+  <emu-alg>
+    1. Return *false*.
+  </emu-alg>
+</emu-clause>

test/lint.js

@@ -253,6 +253,11 @@ describe('linting whole program', () => {
           <emu-clause id="i10">
             <h1>Example ( _a_ <del>[ , _b_ ] </del>)</h1>
           </emu-clause>
+          <emu-clause id="i11" type="abstract operation">
+            <h1>Example ( ): a thing (which has a parenthetical)</h1>
+            <dl class="header">
+            </dl>
+          </emu-clause>
       `);
     });
   });