add redefinition support to structured headers (#428)

bakkot · web-flow · commit e6e10d7ad1ec · 2022-03-31T12:16:33.000-07:00
diff --git a/spec/index.html b/spec/index.html
@@ -196,6 +196,7 @@ <h1>Structured Headers</h1>
           <ul>
             <li><b>description:</b> An explanation of the operation's behaviour.</li>
             <li><b>for:</b> The type of value to which a clause of type "concrete method" or "internal method" applies.</li>
+            <li><b>redefinition:</b> If "true", the name of the operation will not automatically link (i.e., it will not automatically be given an aoid).</li>
           </ul>
         </li>
       </ol>
diff --git a/src/Clause.ts b/src/Clause.ts
@@ -182,7 +182,12 @@ export default class Clause extends Builder {
       header.innerHTML = formattedHeader;
     }
 
-    const { description, for: _for, effects } = parseStructuredHeaderDl(this.spec, type, dl);
+    const {
+      description,
+      for: _for,
+      effects,
+      redefinition,
+    } = parseStructuredHeaderDl(this.spec, type, dl);
 
     const paras = formatPreamble(
       this.spec,
@@ -197,28 +202,30 @@ export default class Clause extends Builder {
     );
     dl.replaceWith(...paras);
 
-    if (this.node.hasAttribute('aoid')) {
-      this.spec.warn({
-        type: 'attr',
-        ruleId: 'header-format',
-        message: `nodes with structured headers should not include an AOID`,
-        node: this.node,
-        attr: 'aoid',
-      });
-    } else if (
-      name != null &&
-      type != null &&
-      [
-        'abstract operation',
-        'sdo',
-        'syntax-directed operation',
-        'host-defined abstract operation',
-        'implementation-defined abstract operation',
-        'numeric method',
-      ].includes(type)
-    ) {
-      this.node.setAttribute('aoid', name);
-      this.aoid = name;
+    if (!redefinition) {
+      if (this.node.hasAttribute('aoid')) {
+        this.spec.warn({
+          type: 'attr',
+          ruleId: 'header-format',
+          message: `nodes with structured headers should not include an AOID`,
+          node: this.node,
+          attr: 'aoid',
+        });
+      } else if (
+        name != null &&
+        type != null &&
+        [
+          'abstract operation',
+          'sdo',
+          'syntax-directed operation',
+          'host-defined abstract operation',
+          'implementation-defined abstract operation',
+          'numeric method',
+        ].includes(type)
+      ) {
+        this.node.setAttribute('aoid', name);
+        this.aoid = name;
+      }
     }
 
     this.effects.push(...effects);
diff --git a/src/header-parser.ts b/src/header-parser.ts
@@ -401,9 +401,10 @@ export function parseStructuredHeaderDl(
   spec: Spec,
   type: string | null,
   dl: Element
-): { description: Element | null; for: Element | null; effects: string[] } {
+): { description: Element | null; for: Element | null; effects: string[]; redefinition: boolean } {
   let description = null;
   let _for = null;
+  let redefinition: boolean | null = null;
   let effects: string[] = [];
   for (let i = 0; i < dl.children.length; ++i) {
     const dt = dl.children[i];
@@ -474,6 +475,34 @@ export function parseStructuredHeaderDl(
         }
         break;
       }
+      case 'redefinition': {
+        if (redefinition != null) {
+          spec.warn({
+            type: 'node',
+            ruleId: 'header-format',
+            message: `duplicate "redefinition" attribute`,
+            node: dt,
+          });
+        }
+        const contents = (dd.textContent ?? '').trim();
+        if (contents === 'true') {
+          redefinition = true;
+        } else if (contents === 'false') {
+          redefinition = false;
+        } else {
+          spec.warn({
+            type: 'contents',
+            ruleId: 'header-format',
+            message: `unknown value for "redefinition" attribute (expected "true" or "false", got ${JSON.stringify(
+              contents
+            )})`,
+            node: dd,
+            nodeRelativeLine: 1,
+            nodeRelativeColumn: 1,
+          });
+        }
+        break;
+      }
       case '': {
         spec.warn({
           type: 'node',
@@ -494,7 +523,7 @@ export function parseStructuredHeaderDl(
       }
     }
   }
-  return { description, for: _for, effects };
+  return { description, for: _for, effects, redefinition: redefinition ?? false };
 }
 
 export function formatPreamble(
diff --git a/test/baselines/generated-reference/structured-headers.html b/test/baselines/generated-reference/structured-headers.html
@@ -17,20 +17,26 @@ <h1><span class="secnum">1</span> ExampleAO ( param [ , param2 ] )</h1>
   <emu-alg><ol><li>Algorithm steps go here.</li></ol></emu-alg>
 </emu-clause>
 
+<emu-clause id="sec-exampleao" type="abstract operation">
+  <h1><span class="secnum">2</span> ExampleAO ( )</h1>
+  <p>The abstract operation ExampleAO takes no arguments. It redefines an existing algorithm. 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-exampleao2" type="abstract operation" aoid="ExampleAO2">
-  <h1><span class="secnum">2</span> <ins>ExampleAO2 ( param )</ins></h1>
+  <h1><span class="secnum">3</span> <ins>ExampleAO2 ( param )</ins></h1>
   <p>The abstract operation ExampleAO2 takes argument param (an <emu-xref href="#integer"><a href="https://tc39.es/ecma262/#integer">integer</a></emu-xref>). 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-exampleao3" type="abstract operation" aoid="ExampleAO3">
-  <h1><span class="secnum">3</span> ExampleAO3 ( <del>param</del> )</h1>
+  <h1><span class="secnum">4</span> ExampleAO3 ( <del>param</del> )</h1>
   <p>The abstract operation ExampleAO3 takes argument <del>param (an <emu-xref href="#integer"><a href="https://tc39.es/ecma262/#integer">integer</a></emu-xref>)</del>. 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-grammar">
-  <h1><span class="secnum">4</span> This and That</h1>
+  <h1><span class="secnum">5</span> This and That</h1>
   <emu-grammar type="definition"><emu-production name="PrimaryExpression" id="prod-PrimaryExpression">
     <emu-nt><a href="#prod-PrimaryExpression">PrimaryExpression</a></emu-nt> <emu-geq>:</emu-geq> <emu-rhs a="jo4mwtvh" id="prod-6iVAqhjf">
         <emu-t>this</emu-t>
@@ -41,7 +47,7 @@ <h1><span class="secnum">4</span> This and That</h1>
 </emu-production>
 </emu-grammar>
   <emu-clause id="sec-isthis" type="sdo" aoid="IsThis">
-    <h1><span class="secnum">4.1</span> IsThis</h1>
+    <h1><span class="secnum">5.1</span> IsThis</h1>
     <p>The <emu-xref href="#sec-algorithm-conventions-syntax-directed-operations"><a href="https://tc39.es/ecma262/#sec-algorithm-conventions-syntax-directed-operations">syntax-directed operation</a></emu-xref> IsThis takes no arguments. It is an example. It is defined piecewise over the following productions:</p>
     <emu-grammar><emu-production name="PrimaryExpression" collapsed="">
     <emu-nt><a href="#prod-PrimaryExpression">PrimaryExpression</a></emu-nt> <emu-geq>:</emu-geq> <emu-rhs a="jo4mwtvh" id="prod-oDKnYE2s"><emu-t>this</emu-t></emu-rhs>
@@ -55,7 +61,7 @@ <h1><span class="secnum">4.1</span> IsThis</h1>
     <emu-alg><ol><li>Return <emu-val>false</emu-val>.</li></ol></emu-alg>
   </emu-clause>
   <emu-clause id="sec-isthat" type="sdo" aoid="IsThat">
-    <h1><span class="secnum">4.2</span> IsThat</h1>
+    <h1><span class="secnum">5.2</span> IsThat</h1>
     <p>The <emu-xref href="#sec-algorithm-conventions-syntax-directed-operations"><a href="https://tc39.es/ecma262/#sec-algorithm-conventions-syntax-directed-operations">syntax-directed operation</a></emu-xref> IsThat takes argument <var>ignored</var> (an example). It is defined piecewise over the following productions:</p>
     <emu-grammar><emu-production name="PrimaryExpression" collapsed="">
     <emu-nt><a href="#prod-PrimaryExpression">PrimaryExpression</a></emu-nt> <emu-geq>:</emu-geq> <emu-rhs a="jo4mwtvh" id="prod-QDgm4qgx"><emu-t>this</emu-t></emu-rhs>
@@ -71,13 +77,13 @@ <h1><span class="secnum">4.2</span> IsThat</h1>
 </emu-clause>
 
 <emu-clause id="sec-example-return-type" type="abstract operation" aoid="ExampleAO3">
-  <h1><span class="secnum">5</span> ExampleAO3 ( param )</h1>
+  <h1><span class="secnum">6</span> ExampleAO3 ( param )</h1>
   <p>The abstract operation <emu-xref aoid="ExampleAO3" id="_ref_0"><a href="#sec-exampleao3">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>
+  <h1><span class="secnum">7</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>
diff --git a/test/baselines/sources/structured-headers.html b/test/baselines/sources/structured-headers.html
@@ -23,6 +23,19 @@ <h1>
   </emu-alg>
 </emu-clause>
 
+<emu-clause id="sec-exampleao" type="abstract operation">
+  <h1>ExampleAO ( )</h1>
+  <dl class='header'>
+    <dt>description</dt>
+    <dd>It redefines an existing algorithm.</dd>
+    <dt>redefinition</dt>
+    <dd>true</dd>
+  </dl>
+  <emu-alg>
+    1. Algorithm steps go here.
+  </emu-alg>
+</emu-clause>
+
 <emu-clause id="sec-exampleao2" type="abstract operation">
   <h1>
     <ins>ExampleAO2 (
diff --git a/test/errors.js b/test/errors.js
@@ -660,6 +660,26 @@ ${M}      </pre>
         },
         { lintSpec: true }
       );
+
+      await assertError(
+        positioned`
+          <emu-clause id="sec-test" type="abstract operation">
+          <h1>Example ( )</h1>
+          <dl class='header'>
+            <dt>redefinition</dt>
+            <dd>true</dd>
+            ${M}<dt>redefinition</dt>
+            <dd>false</dd>
+            </dl>
+          </emu-clause>
+        `,
+        {
+          ruleId: 'header-format',
+          nodeType: 'dt',
+          message: 'duplicate "redefinition" attribute',
+        },
+        { lintSpec: true }
+      );
     });
 
     it('"for" for AO', async () => {
@@ -700,6 +720,27 @@ ${M}      </pre>
       );
     });
 
+    it('unknown value for redefinition', async () => {
+      await assertError(
+        positioned`
+          <emu-clause id="sec-test" type="abstract operation">
+          <h1>Example ( )</h1>
+          <dl class='header'>
+            <dt>redefinition</dt>
+            <dd>${M}not true</dd>
+          </dl>
+          </emu-clause>
+        `,
+        {
+          ruleId: 'header-format',
+          nodeType: 'dd',
+          message:
+            'unknown value for "redefinition" attribute (expected "true" or "false", got "not true")',
+        },
+        { lintSpec: true }
+      );
+    });
+
     it('empty attribute', async () => {
       await assertError(
         positioned`
diff --git a/test/lint.js b/test/lint.js
@@ -504,6 +504,7 @@ describe('linting whole program', () => {
         }
       );
     });
+
     it('for clauses', async () => {
       await assertLint(
         positioned`
@@ -562,5 +563,54 @@ describe('linting whole program', () => {
         }
       );
     });
+
+    it('is present when using structured headers without explict AOIDs', async () => {
+      await assertLint(
+        positioned`
+          <emu-clause id="sec-example" type="abstract operation">
+            <h1>Foo ( _param_ )</h1>
+            <dl class='header'>
+              <dt>description</dt>
+              <dd>It is an example.</dd>
+            </dl>
+          </emu-clause>
+
+          ${M}<emu-clause id="sec-example-redef" type="abstract operation">
+            <h1>Foo ( _param_ )</h1>
+            <dl class='header'>
+              <dt>description</dt>
+              <dd>It redefines an existing algorithm.</dd>
+            </dl>
+          </emu-clause>
+          `,
+        {
+          ruleId: 'duplicate-definition',
+          nodeType: 'emu-clause',
+          message: 'duplicate definition "Foo"',
+        }
+      );
+    });
+
+    it('is suppressed when using `redefinition: true`', async () => {
+      await assertLintFree(`
+        <emu-clause id="sec-example" type="abstract operation">
+          <h1>Foo ( _param_ )</h1>
+          <dl class='header'>
+            <dt>description</dt>
+            <dd>It is an example.</dd>
+          </dl>
+        </emu-clause>
+
+        <emu-clause id="sec-example-redef" type="abstract operation">
+          <h1>Foo ( _param_ )</h1>
+          <dl class='header'>
+            <dt>description</dt>
+            <dd>It redefines an existing algorithm.</dd>
+            <dt>redefinition</dt>
+            <dd>true</dd>
+          </dl>
+        </emu-clause>
+      `);
+    });
   });
 });
