Consider rewriting the markdown checker in rust

[jodh-intel]

The check-markdown tool is used by the static-checks.sh script called by the CI.

Although the current golang implementation of check-markdown is ok, it isn't perfect as the blackfriday package it uses seems fragile (see https://github.com/kata-containers/tests/blob/main/cmd/check-markdown/hack.go).

Since we're moving everything else to rust, it might be worth considering rewriting check-markdown in rust too.

If anyone is interested, please add a comment here before starting work on it! 😄

[Christopher-C-Robinson]

@jodh-intel, I have some interest in this one.

[jodh-intel]

Thanks @Christopher-C-Robinson! The first step is going to be to identify a good markdown parsing crate to use. I quick look suggests these are two popular ones:

• https://crates.io/crates/comrak
• https://github.com/wooorm/markdown-rs

If you look at the golang markdown checker, it uses the blackfriday golang package to handle the parsing of the doc into an AST. Markdown is a pretty permissive language so the parsers tend to "always work" and generate a tree of nodes. The rust tool (like the go version) will need to walk through the tree and perform checks on the different nodes and groups of nodes to determine whether we believe the markdown file is "valid". This regex shows most of the error scenarios the golang tool checks for:

$ git clone https://github.com/kata-containers/tests
$ cd tests/cmd/check-markdown
$ grep -Er 'errors.new|fmt.Errorf'                                                                                                          main [0]
utils.go:               return "", "", fmt.Errorf("invalid link %s: expected %d fields, found %d", linkName, expectedFields, foundFields)
utils.go:               return "", fmt.Errorf("need heading name")
utils.go:               return fmt.Errorf("expected %v node, found %v", expectedType, node.Type)
add.go:                 return "", fmt.Errorf("document root %q does not exist", docRoot)
heading.go:             return Heading{}, fmt.Errorf("heading name cannot be blank")
heading.go:             return Heading{}, fmt.Errorf("heading markdown name cannot be blank")
heading.go:             return Heading{}, fmt.Errorf("level needs to be atleast 1")
main.go:                return fmt.Errorf("no handler for format %q", format)
doc.go: return fmt.Errorf("file=%q: %s", d.Name, s)
display.go:             return fmt.Errorf("unknown show option: %v", what)
parse.go:               return fmt.Errorf("found %d parse error%s:\n%s",

A lot of what the checker does is checking markdown links between documents as we want to guarantee that all markdown links are valid. That's harder than it sounds as checking a single markdown file may link to every other markdown file in the repo (and then back to itself potentially!)

Separate from markdown links are URLs in markdown docs. Validating URLs isn't the focus of the current golang tool as we actually handle that in the CI here using:

• The xurls command to extract URLs from markdown files.
• the check_url() function in the statick-checks.sh script (that calls the curl command to actually connect to the URL).

However, it would be good if eventually the rust markdown checker could handle checking URLs itself (extracting the URLs from the markdown, verifying that they are syntactically valid addresses, and then optionally connecting to the URL to determine if those URLs are valid/alive still. But that doesn't need to be done for this issue ;)

One last comment: it would be a good idea to be familiar with the GitHub Flavoured Markdown spec for this piece of work:

• https://github.github.com/gfm

[jodh-intel]

@Christopher-C-Robinson - Here's how I'd break this task down:

• Read the source for the existing golang tool, particularly these files:
  • https://github.com/kata-containers/tests/blob/main/cmd/check-markdown/parse.go
  • https://github.com/kata-containers/tests/blob/main/cmd/check-markdown/node.go
• Look at some of the golang tests for the golang tool, particularly the link tests:
  • https://github.com/kata-containers/tests/blob/main/cmd/check-markdown/link_test.go
• Choose a markdown parsing crate that can create an AST of nodes for the various bits of the doc (titles, links, etc).
• Write a simple rust program that uses the crate to parse the doc.
• Update the rust program so that you visit all the nodes and dump out some info about them.
• Refine the program further so that you only visit the node types that you care about (links, titles, etc).
• Start adding some basic checks for the nodes.
• Add the command line parsing using the clap crate.
  Hint: It takes a bit of time to get familiar with clap. I'd consider writing a simple program that just allows you to test out various clap features. Once you're comfortable with that simple program, think about adding the clap code to your markdown parsing code.

We use clap everywhere so looking at some of the other tools should help too:

• https://github.com/kata-containers/kata-containers/tree/main/src/tools/agent-ctl
• https://github.com/kata-containers/kata-containers/tree/main/src/tools/kata-ctl

Also, I believe @gabevenberg is using it for kata-containers/kata-containers#5350.

As shown, there are quite a few steps so you might want to consider pairing up with someone else to work on this, or limiting the scope of what you plan to implement. We can more about this in the meeting on Friday or on Slack of course ;)

[Toreseen]

@jodh-intel I have joined @Christopher-C-Robinson and we are teaming up to attempt to tackle this issue.

[jodh-intel]

@Toreseen - great! ;)

[jodh-intel]

As discussed with @Christopher-C-Robinson and @Toreseen today, once you've got a basic program that can iterate through all the markdown node types, you'll need to ensure it can access "heading" links and markdown links (not URLs).

You might need to save these nodes to a hash or a list (a Vec in rust). Once that's possible, you can write the first check which will validate the all markdown links that link to other parts of the current document (not URLs) are valid.
To do this, you'll need a function to map markdown heading text (such as # I am a heading) to the equivalent link name (#i-am-a-heading). I'd recommend looking at the existing golang markdown checker to see more of what is needed to validate headings. Once that's working, you can expand the check to consider links to other docs.

Checking markdown link in current file

## Section 1

foo

## Section 2

- This is a [valid link](#section-1).
- This is an [invalid link](#invalid-section).

Checking markdown link in another file

Note: This example shows a relative link to another document so the checker needs to ensure:

1. That the file ../docs/design/README.md exists.
2. That the heading "section-wibble" exists in that file.

This is a link to a [different file](../docs/design/README.md#section-wibble).