readme-inspector

Inspect GitHub (and GitHub Enterprise) repositories for the presence and quality of READMEs.

Table of contents

• 1. Installation
• 2. Usage
• 3. API
  • 3.1. authenticate({token, type, key})
    • 3.1.1. Parameters
    • 3.1.2. Returns void
    • 3.1.3. Example
  • 3.2. check(ower, repo, ref)
    • 3.2.1. Parameters
    • 3.2.2. Returns Promise
    • 3.2.3. Examples
  • 3.3. getReadmeInfo(owner, repo, ref)
    • 3.3.1. Parameters
    • 3.3.2. Returns Promise
    • 3.3.3. Examples
  • 3.4. getReadmeScore(url)
  • 3.5. ReadmeScore
    • 3.5.1. for(url: String): Promise
      • 3.5.1.1. Parameters
      • 3.5.1.2. Returns Promise
      • 3.5.1.3. Examples
• 4. Version
• 5. Contributing
• 6. License

1. Installation

readme-inspector is written in JavaScript (CommonJS) for Node.js versions 7.6.0 or higher (for async/await support).

$ npm install --save readme-inspector

Recommendation: To avoid rate-limiting, you should create a personal access token and save your personal access token in an environment variable called GH_TOKEN.

• MacOS and Unix

  $ mkdir -p /usr/local/etc/readme-inspector/envvars/
  $ touch /usr/local/etc/readme-inspector/envvars/.env
  $ echo "GH_TOKEN={your-personal-access-token-value}" > \
    /usr/local/etc/readme-inspector/envvars/.env

• Windows

   md -p C:\usr\local\etc\readme-inspector\envvars\
   touch C:\usr\local\etc\readme-inspector\envvars\.env
   echo "GH_TOKEN="{your-personal-access-token-value}" > C:\usr\local\etc\readme-inspector\envvars\.env

---

Click here for detailed .env variable initialization instructions

# .env.schema, committed to repo

## See https://github.com/keithmorris/node-dotenv-extended/#readme
## ⛔️
## 🚫  DO NOT COMMIT YOUR ACTUAL .env file to version control.
## 🚫  It should only include environment-specific values such
## 🚫  as database passwords or API keys.
## 🚫  Your production database should have a different password
## 🚫  than your development database.

# ENV VARS required for readme-inspector
## Add values to these ENV VARs and save to
## {your-project-root-directory}/.env

# ▫️ OPTIONAL env vars:
API_ENDPOINT_README_SCORE=
CODACY_PROJECT_TOKEN=
GA_README_INSPECTOR=

# 🔸 RECOMMENDED vars (to extend GitHub API rate limits)
GH_TOKEN=
GITHUB_ACCESS_TOKEN=

---

2. Usage

const readmeInspector = require('readme-inspector')

// Recommended: authenticate to avoid rate limts
readmeInspector.authenticate({
  token: process.env.GH_TOKEN,
  type: 'oauth'
})

const results = await readmeInspector.check(
  'gregswindle',
  'github-resource-converter'
)
// => Formatted and stringified
/*
{
  "err": null,
  "isPresent": true,
  "scoreData": {
    "score": 100,
    "url": "https://github.com/gregswindle/github-resource-converter",
    "breakdown": {
      "cumulative_code_block_length": 10,
      "has_lists?": 10,
      "low_code_block_penalty": 0,
      "number_of_code_blocks": 40,
      "number_of_gifs": 0,
      "number_of_images": 15,
      "number_of_non_code_sections": 30
    }
  },
  "value": {
    "name": "README.md",
    "path": "README.md",
    "sha": "c4e2170a790916adefbb378f0fbb4ac458314d0e",
    "size": 61697,
    "url": "https://api.github.com/repos/gregswindle/github-resource-converter/contents/README.md?ref=master",
    "html_url": "https://github.com/gregswindle/github-resource-converter/blob/master/README.md",
    "git_url": "https://api.github.com/repos/gregswindle/github-resource-converter/git/blobs/c4e2170a790916adefbb378f0fbb4ac458314d0e",
    "download_url": "https://raw.githubusercontent.com/gregswindle/github-resource-converter/master/README.md",
    "type": "file",
    "content": "...",
    "encoding": "base64",
    "_links": {
      "self": "https://api.github.com/repos/gregswindle/github-resource-converter/contents/README.md?ref=master",
      "git": "https://api.github.com/repos/gregswindle/github-resource-converter/git/blobs/c4e2170a790916adefbb378f0fbb4ac458314d0e",
      "html": "https://github.com/gregswindle/github-resource-converter/blob/master/README.md"
    }
  }
}
*/

3. API

Test readme-inspector in your Web browser .

The readmeInspector module detects whether or not a README document exists at the root of a GitHub or GitHub Enterprise repository. If a README exists, it can evaluate the README's quality and provide a numerical score from 0 to 100, where 0 is the lowest quality and 100 is the highest.

3.1. authenticate({token, type, key})

Most GitHub API calls don't require authentication. Rules of thumb:

1. If you can see the information by visiting the site without being logged in, you don't have to be authenticated to retrieve the same information through the API.
2. If you want to change data, you have to be authenticated.

octokit/rest.js. (2018). GitHub. Retrieved 21 March 2018, from https://github.com/octokit/rest.js#authentication

3.1.1. Parameters

Name	Type	Description	Notes
key	String
token	String
type	Enum	basic, oauth, oauth-key-secret, token, and integration

3.1.2. Returns void

authenticate does not return a value.

3.1.3. Example

// Token (https://github.com/settings/tokens)
// Load your GH_TOKEN or GITHUB_ACCESS_TOKEN from
// environment variables:
const dotenvExtended = require('dotenv-extended')
const envConfig = dotenvExtended.config()

const readmeInspector = require('readme-inspector')

readmeInspector.authenticate({
  token: envConfig.GH_TOKEN,
  type: 'token'
})

3.2. check(ower, repo, ref)

A convenience method that

• Attempts to GET a repository's root-level README, and, if found,
• Scores the README.

/repos/:owner/:repo/readme

3.2.1. Parameters

Field	Type	Description
owner	String
repo	String
ref	String	The name of the commit/branch/tag. Default: the repository’s default branch (usually master).

3.2.2. Returns Promise<ReadmeInfo>

ReadmeInfo's interface (as a NullObject):

{
  'err': null,
  'isPresent': null,
  'scoreData': {
    'breakdown': {
      'cumulativeCodeBlockLength': 0,
      'hasLists': 0,
      'lowCodeBlockPenalty': 0,
      'numberOfCodeBlocks': 0,
      'numberOfGifs': 0,
      'numberOfImages': 0,
      'numberOfNonCodeSections': 0
    },
    'err': null,
    'score': 0,
    'url': null
  },
  'value': null
}

3.2.3. Examples

• async/await:

  const readmeInfo = await readmeInspector.check({
    owner: 'commonality',
    ref: 'GH-1-feat-inspect-readmes',
    repo: 'readme-inspector'
  })

• Promise:

  readmeInspector
    .check({
      owner: 'commonality',
      ref: 'GH-1-feat-inspect-readmes',
      repo: 'readme-inspector'
    })
    .then(readmeInfo => {})
    .catch(err => {})

3.3. getReadmeInfo(owner, repo, ref)

Retrieves README information without any ScoreData.

/repos/:owner/:repo/readme

3.3.1. Parameters

Field	Type	Description
owner	String
repo	String
ref	String	The name of the commit/branch/tag. Default: the repository’s default branch (usually master).

3.3.2. Returns Promise<ReadmeInfo>

ReadmeInfo's interface (as a NullObject):

{
  'err': null,
  'isPresent': null,
  'scoreData': {
    'breakdown': {
      'cumulativeCodeBlockLength': 0,
      'hasLists': 0,
      'lowCodeBlockPenalty': 0,
      'numberOfCodeBlocks': 0,
      'numberOfGifs': 0,
      'numberOfImages': 0,
      'numberOfNonCodeSections': 0
    },
    'err': null,
    'score': 0,
    'url': null
  },
  'value': null
}

3.3.3. Examples

• async/await:

  const readmeInfo = await readmeInspector.getReadmeInfo({
    owner: 'commonality',
    ref: 'GH-1-feat-inspect-readmes',
    repo: 'readme-inspector'
  })

• Promise:

  readmeInspector
    .getReadmeInfo({
      owner: 'commonality',
      ref: 'GH-1-feat-inspect-readmes',
      repo: 'readme-inspector'
    })
    .then(readmeInfo => {})
    .catch(err => {})

3.4. getReadmeScore(url)

A convenience wrapper that calls the ReadmeScore.for method.

3.5. ReadmeScore

ReadmeScore is an API proxy for @clayallsopp 's readme-score-api .

ScoreMe gives you a numerical score from 0 to 100 for your Github-style README. The intention is to measure complexity, which is a generally correlated with quality.

It won't measure if one README is absolutely better than another, but it will give you a good idea if the README is high-quality, needs more work, or somewhere inbetween.

ScoreMe. (2018). Clayallsopp.github.io. Retrieved 10 April 2018, from http://clayallsopp.github.io/readme-score/

3.5.1. for(url: String): Promise<ScoreData>

Evaluate the README at the root of a GitHub repository.

3.5.1.1. Parameters

Name	Type	Description
url	String	The URL, or slug of the repository to be evaluated for a README.

3.5.1.2. Returns Promise<ScoreData>

• ScoreData as a NullObject (see lib/score-data):
  

  {
    breakdown: {
      cumulativeCodeBlockLength: 0
      hasLists: 0
      lowCodeBlockPenalty: 0
      numberOfCodeBlocks: 0
      numberOfGifs: 0
      numberOfImages: 0
      numberOfNonCodeSections: 0
    },
    err: null,
    score: 0
    url: null
  }

3.5.1.3. Examples

• URL:

  const inspector = require('readme-inspector')
  
  const url = 'https://github.com/gregswindle/github-resource-converter'
  
  const result = inspector.readmeScore.for(url)
  /** =>
   * {
   *   breakdown: {
   *    cumulativeCodeBlockLength: 10
   *    hasLists: 10
   *    lowCodeBlockPenalty: 0
   *    numberOfCodeBlocks: 40
   *    numberOfGifs: 0
   *    numberOfImages: 15
   *    numberOfNonCodeSections: 30
   *  },
   *  err: null,
   *  score: 100
   *  url: 'https://github.com/gregswindle/github-resource-converter'
   * }
   */

• Repository slug:

  const inspector = require('readme-inspector')
  
  const slug = 'gregswindle/github-resource-converter'
  
  const result = inspector.readmeScore.for(slug)

4. Version

View the Change Log and Releases for details.

5. Contributing

We welcome contributions with GitHub issues and pull requests.

---

---

Before embarking on a significant change, please follow these guidelines:

1. Create an issue—e.g., a defect ("bug") report or a feature request—to propose changes.

   Exceptions:

   If you're working on documentation and fixing something simple like a typo or an easy bug, go ahead and make a pull request.

2. Follow the CONTRIBUTING guidelines.

   Why:

   Standards and guidelines make communication easier. If you're willing and able to program—or want to learn how— following the guidelines will increase the likelihood of having your changes added to readme-inspector.

3. Read the Code of Conduct.
   

4. Make a pull request when you're ready for other to review your changes (or you get stuck somewhere).

   Never created a pull request?

   No problem: this free online training covers most of the conventions in the CONTRIBUTING guidelines.)

6. License

MIT © commonality

---