feat: @actions/core extensions for markdown summary

[robherley]

Closes: https://github.com/github/c2c-actions-checks/issues/280

This exposes a new class instance to @actions/core, core.markdownSummary. It's a singleton that has an internal buffer with utility methods to facilitate the creation of HTML elements in a markdown summary for a job.

The API is designed to be chainable, like the following:

await core.markdownSummary
  .addHeading('Test Results')
  .addTable([
    [{data: 'File', header: true}, {data: 'Result', header: true}],
    ['foo.js', 'Pass ✅'],
    ['bar.js', 'Fail ❌'],
    ['foo.js', 'Pass ✅']
  ])
  .addDetails('📚 View raw output', 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.')
  .addQuote('With great power comes great responsibility')
  .addLink('Check out this site!', 'https://github.com')
  .addSeparator()
  .write()

Would result in:

👉 HTML 👈

<h1>Test Results</h1>
<table><tr><th>File</th><th>Result</th></tr><tr><td>foo.js</td><td>Pass ✅</td></tr><tr><td>bar.js</td><td>Fail ❌</td></tr><tr><td>foo.js</td><td>Pass ✅</td></tr></table>
<details><summary>📚 View raw output</summary>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</details>
<blockquote>With great power comes great responsibility</blockquote>
<a href="https://github.com">Check out this site!</a>
<hr>

👉 Rendered markdown 👈

Test Results

File	Result
foo.js	Pass ✅
bar.js	Fail ❌
foo.js	Pass ✅

📚 View raw output

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

With great power comes great responsibility

Check out this site!

---

Or, since a buffer is built internally it can be used like so:

const headings = ['one', 'two', 'three', 'four', 'five', 'six']
headings.forEach((text, i) => {
  core.markdownSummary.addHeading(text, i + 1)
})

await core.markdownSummary.write()

Would result in:

👉 HTML 👈

<h1>one</h1>
<h2>two</h2>
<h3>three</h3>
<h4>four</h4>
<h5>five</h5>
<h6>six</h6>

👉 Rendered markdown 👈

one

two

three

four

five

six

Any markdownSummary.add* method first adds to an internal buffer. It is not until the final .write() that it gets append to the $GITHUB_STEP_SUMMARY file or .write(true) to completely overwrite the $GITHUB_STEP_SUMMARY file.

If the users requires custom markup, the .add() method allows for raw text to be added to the buffer. Utility methods like emptyBuffer() to empty a buffer without writing and isBufferEmpty() are included as well.

Since all the actual rendering gets passed through dotcom's HTML rendering pipeline we don't need to worry about sanitizing any of the data.

[SrRyan]

🚀

[LayZeeDK]

question: Is the write(overwrite: boolean) pattern used elsewhere in the toolkit? Did you consider write(options: { overwrite: boolean }) to leave room for future options?

[robherley]

I don't believe it's an existing pattern. I do like the idea of having an options object for extensibility. And I think it'll improve readability as well, ie: write(true) vs write({overwrite: true}). I'll make the changes, thanks for the suggestion!