Half Baked Idea: README Linter Using the GitHub API

It started as a simple idea: let’s explore the awesomeness of the new GraphQL API by building a tiny app. Think Travis-CI but for writing. Maybe it could check spelling, grade level, and possibly help with adverbs the way hemingwayapp.com does.

Maybe that app could help people use pull-requests during editorial reviews, much like how tests help developers with code reviews.

It lead to a rather simple question:

What do I have to do to get the following to work?

OK so that’s what I want to do, I researched and built the pieces but when it came time to actually building the entire node app, I stopped short.

That makes this is a half-baked idea: I’ve verified the individual pieces of tech work, but am stopping because I don’t want to actually build an entire product.

What tech would I need to build in order to do is? Here are the broad strokes:

0. Write-Good: the npm module to test our READMEs

There’s a rather clever npm module write-good which you can run as a CLI. Example from their docs:

1
2
3
4
5
6
7

$ write-good README.md

In README.md
=============
 = writeGood('So the cat was stolen.');
                         ^^^^^^^^^^
"was stolen" is passive voice on line 20 at column 40

I figure we can use this to test a repo’s README.

1. GitHub API: AccessToken with repo:status access

We’ll need to get an AccessToken since each of our GitHub API calls will require it. We can either:

1. Create a personal access token
2. Use oAuth to sign in. If you were building out an application, this is what you’d need to do.

For personal access tokens, you can follow instructions here.

For oAuth signin, you can duck-duck-go for “Sign in With GitHub”. In Rails, omniauth is the dominant way forward. In Node/Express land, I found the options less hospitable, but the npm package passport-github2 is very well done.

1
2
3
4

POST https://api.github.com/graphql
HEADERS
  ContentType: application/json
  Authorization: Bearer $TOKENGOESHERE

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

POST /repos/:owner/:repo/hooks
HEADERS
  ContentType: application/json
  Authorization: Bearer $TOKENGOESHERE
BODY
{
  "name": "readme-good",
  "active": true,
  "events": [
    "pull_request"
  ],
  "config": {
    "url": "http://example.com/webhook",
    "content_type": "json"
  }
}

1
2
3
4
5
6
7
8
9
10
11

POST /repos/:owner/:repo/statuses/:commitsha
HEADERS
  ContentType: application/json
  Authorization: Bearer $TOKENGOESHERE
BODY
{
  "state": "pending",
  "target_url": "https://example.com/builds/BUILD_ID_HERE",
  "description": "Building...",
  "context": "readme-good/status"
}

1
2
3
4
5
6
7
8
9
10
11

POST /repos/:owner/:repo/statuses/:commitsha
HEADERS
  ContentType: application/json
  Authorization: Bearer $TOKENGOESHERE
BODY
{
  "state": "success",
  "target_url": "https://example.com/builds/BUILD_ID_HERE",
  "description": "All is good...",
  "context": "readme-good/status"
}