Extended markdown syntax used in issue-runner

[eine]

While chatting with @mithro, he mentioned this project and I let him know about issue-runner. As explained in the README, the main purpose of issue-runner is extracting reproducible MWEs from Markdown files. More precisely, from the first comment in GitHub issues. issue-runner extracts source files, (optionally) invokes docker, executed the entrypoint and cleans up. I told Tim about the extended markdown syntax used in issue-runner and he suggested to open this issue for discussion.

issue-runner is composed of two different pieces. There is a golang CLI tool that can process local markdown files, GitHub issue refs or URLs (see https://eine.github.io/issue-runner/#cli). It can process multiple MWEs:

issue-runner 'tests/md/vunit-sh.md' 'VUnit/vunit#337' 'ghdl/ghdl#579'
issue-runner 'ghdl/ghdl#584' 'https://raw.githubusercontent.com/eine/issue-runner/master/tests/md/vunit-py.md'

The CLI tool can be used as a docker container.

As a matter of fact, an ealier iteration of the CLI tool was written in Python: https://github.com/eine/issue-runner/tree/py

On the other hand, there is a TypeScript GitHub Action (https://github.com/eine/issue-runner/tree/master/ts) which can be used in GitHub Action workflows. It is expected to be triggered when issues are opened or edited. It can also be triggered after a tagged release, for checking all open issues in a repo. For instance, this is the summary of analysing ghdl/ghdl: https://github.com/eine/issue-runner/runs/1179157803?check_suite_focus=true#step:8:2839. Ideally, the result of each execution should be reported back in the issue, but this feature is not implemented yet.

---

The extended Markdown syntax is explained in https://eine.github.io/issue-runner/#supported-markdown-syntax. For code blocks to be considered part of a MWE, :file: needs to be specified. It can be done either in the markdown decoration or as a comment in the language:

```sh :file: hello.sh
#!/usr/bin/env sh
echo "Hello world!"
```

```sh
#!/usr/bin/env sh
echo "Hello world!"
#:file: hello.sh
```

Attached/linked text files and tarballs are also supported. These need :mwe: as a keyword:

[:mwe:filename.ext.txt](URL)
[:mwe:filename.tar.gz](URL)

Then main entrypoint is whichever file named run. Alternatively, a container image can be defined:

```sh :image: debian:buster-slim
echo "Hello world!"
```

NOTE: if the CLI tool is executed as a container and the extraced MWE needs to be executed in a container, the socket needs to be shared for sibling containers to be spawned. See https://eine.github.io/issue-runner/#cli.

---

According to the README of this repo, tuttest does not support decorated markdown code blocks. Hence, I think it'd be interesting to extend tuttest for supporting issue-runner's syntax. It seems that the usage of name in tuttest is equivalent to file in issue-runner.

[mithro]

@mgielda - PTAL and tell us what you think? Using a similar syntax for issue-runner and tuttest seems like a potentially good idea?

[mgielda]

Thanks for the suggestion. I think going forward we will most likely need to support multiple syntaxes, since there are so many flavors of markdown. So we probably should include your syntax too :)

Interesting project BTW!