Improve linking for abstract&concrete methods

[nicolo-ribaudo]

Ref #391

The first commit:

• adds support for structured headers in abstract method declarations. A list of abstract method declarations is introduced by <emu-table type="abstract methods">.
• adds abstract methods as ops to the biblio, so that autolinking will find their references and auto-link to the declaration

The second commit:

• adds concrete methods to the biblio
• introduces an <emu-concrete-method-dfns for="SomeAbstractMethodName">, which auto-expands to a list of definitions for SomeAbstractMethodName

With both together, this code:

  <emu-table type="abstract methods" of="Module Record" id="table-abstract-methods-of-module-records">
    <table>
      <thead>
        <tr>
          <th>Method</th>
          <th>Description</th>
          <th>Definitions</th>
        </tr>
      </thead>
      <tr>
        <td>
          ResolveExport (
            _exportName_: a String,
            <ins>_resolveSet_: a List of Module Records,</ins>
          ): either a Module Record or *null*
        </td>
        <td>It does something when called.</td>
        <td>
          It is defined in the following places:
          <emu-concrete-method-dfns for="ResolveExport"></emu-concrete-method-dfns>
        </td>
      </tr>
    </table>
  </emu-table>

Is rendered like this:

This PR does not introduce yet any checks that the signatures match.

Some questions:

1. Right now the links from usage sides to abstract method definitions just link to the table, should they have more precise links?
2. Usually AO signatures are wrapped in <h1>, but I'm not sure it makes much sense to do it inside a table. Should I do it anyway for consistency?

[bakkot]

This looks great, thank you!

Can you also add a test which confirms that we now get signature-based errors for invocations of abstract methods? E.g. that if we have an abstract method Method with signature ( _x_: a string ), then invoking it as _foo_.Method(~enum~) and _foo_.Method(*"string"*, *"extra"*) both give warnings.

[michaelficarra]

Can we prefix it with the section number?

[bakkot]

I think it should be possible to get that for free by re-using the existing emu-xref machinery by simply not populating textContent here. Alternatively, if that doesn't work because that phase has already run or something, we can export and re-use the relevant function directly.

[nicolo-ribaudo]

Not putting the text content seems to give just the number, without the text. I'll do it manually.

Would we want the number of the section (e.g. 16.2.1.2 Source Text Module Record) or of the specific concrete method that we are linking to (e.g. 16.2.1.7.2.2 Source Text Module Record)?

[nicolo-ribaudo]

I'm going ahead with the full number, since that seems to be more useful when manually looking for the number (e.g. in a printed version), even if the title doesn't match.

[nicolo-ribaudo]

invoking it as _foo_.Method(~enum~)

Is this meant to warn because of the mismatched argument type? I do not seem to be getting that warning even with plain AOs.

[bakkot]

Is this meant to warn because of the mismatched argument type? I do not seem to be getting that warning even with plain AOs.

Sorry, has to be spelled "a String", with the capital letter, to actually work. Full example:

<pre class="metadata">
copyright: false
</pre>
<emu-clause id="example" type="abstract operation">
  <h1>
    Example (
      arg: a String,
    ): ~unused~
  </h1>
  <dl class="header"></dl>
</emu-clause>
<emu-alg>
  1. Perform Example(~enum~).
</emu-alg>

$ ./bin/ecmarkup.js --lint-spec test.emu /dev/null
Warning: inlining assets; this should not be done for production builds.
[2026-01-16T21:03:31.921Z] Warning: test.emu:13:22: argument (~enum~) does not look plausibly assignable to parameter type (String)

[nicolo-ribaudo]

Oh yes that worked, thanks.

[michaelficarra]

🆒

[bakkot]

Looks great but should also get docs (under spec/index.html). I would do it as a subsection of emu-table I guess. I can do that myself in the next couple days if you don't get around to it before then.

[bakkot]

Updated docs but I want to make another couple tweaks first (making for parsing only apply to concrete methods; adding a lint to enforce that the concrete and abstract match).

This PR will be a breaking change (because it enforces that _foo_.Bar() has a corresponding abstract method definition Bar, using the new element), so also I want to hold off on landing it until I get the 262 PR ready as well.

[bakkot]

OK, I'm happy with this, and got ecma262 building: tc39/ecma262#3745