Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: @actions/core extensions for markdown summary #1014

Merged
merged 18 commits into from Apr 20, 2022

Conversation

robherley
Copy link
Member

@robherley robherley commented Mar 2, 2022

Closes: github/c2c-actions-checks#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

FileResult
foo.jsPass
bar.jsFail
foo.jsPass
📚 View raw outputLorem 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.

@robherley robherley marked this pull request as ready for review Mar 3, 2022
@robherley robherley requested a review from a team as a code owner Mar 3, 2022
packages/core/src/markdown-summary.ts Outdated Show resolved Hide resolved
SrRyan
SrRyan approved these changes Mar 3, 2022
Copy link

@SrRyan SrRyan left a comment

🚀

@jtamsut jtamsut self-requested a review Mar 3, 2022
jtamsut
jtamsut approved these changes Mar 3, 2022
packages/core/src/markdown-summary.ts Outdated Show resolved Hide resolved
*
* @returns {Promise<MarkdownSummary>} markdown summary instance
*/
async write(overwrite = false): Promise<MarkdownSummary> {
Copy link

@LayZeeDK LayZeeDK Mar 8, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member Author

@robherley robherley Mar 8, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!

@robherley robherley merged commit 91f9153 into main Apr 20, 2022
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

7 participants