chimi

chimi

Validate JavaScript code from your README.

How it works

chimi parses Markdown files and runs the JavaScript snippets to check if everything is alright.

Installation

$ yarn add chimi --dev
$ npm i chimi --save-dev

# global works too

$ yarn global add chimi
$ npm i -g chimi

Usage

  Run JavaScript snippets from your markdown files

  Usage
  $ chimi -f <file>

  Options
    --file,    -f      File or glob matching multiple files (default: "README.md")
    --help,    -h      Show help
    --silent           Prevent snippets from printing messages through the console
    --version, -v, -V  Show version

  Examples
    $ chimi -f README.md

    $ chimi -f doc/*.md

Configuration

To let chimi find the snippets you have to indicate the snippet language using either js or javascript like so:

```js

```javascript

You can configure chimi using a configuration file, it might be a JSON or JavaScript file and also an object as the chimi property in the package.json:

{
  "dependencies": [
    "trae",
    { "module": "lodash", "name": "_" },
    { "module": "./config", "name": "config" },
    { "module": "es6-promise" }
  ],
  "globals": {
    "answer": 42,
    "add": "(a, b) => a + b",
    "message": "'hello world'",
    "fruits": "['orange', 'apple']",
    "config": "{ port: 8080 }",
  },
  "file": "readme.md",
  "timeout": 5000
}

NOTE: the .chimirc file has to be a valid JSON.

NOTE: if it is a JavaScript file, an object has to be exported.

dependencies: Array<string|object>

A list of dependencies to be required on each snippet.

Pass a string when the variable name and the module to be required are equal. To cover other cases you can pass an object with variable name as the name property, the module as the module property, if the name is missing the require will not have an assignment.

The depenencies in the example will generate these requires:

const trae   = require('trae')
const _      = require('lodash')
const config = require('./config')

require('es6-promise')

These dependencies will be added to your snippet before running it so you don't have to do it on every snippet.

globals: object

A list of variable declarations to add on each snippet. Each key represents the variable name and the value is, well, the value.

The globals in the example will generate these declarations:

let answer  = 42
let add     = (a, b) => a + b
let message = 'hello world'
let fruits  = ['orange', 'apple']
let port    = { port: 8080 }

NOTE: strings must be quoted. E.g. consider the following example.

{
  "globals": {
    "wrong": "hello world"
    "right": "'hello world'"
  }
}

let wrong = hello world
let right = 'hello world'

file: string

Default: README.md.

The path to the file/s you want to parse. It can also be a glob. Be sure to specify only .md files.

timeout: number

Default: 5000.

The time, in miliseconds, to wait for the snippet execution before considering it a failure.

Snippet annotations

Markdown snippets can be annotated by adding extra stuff on the same line as the language. Don't worry this annotations do not show on the web.

Chimi supports the following annotations:

Skip

To skip a snippet:

```js (skip)

TODO

V1

• Tests
• CLI
  • Configuration (.chimi.js(on)?|.chimirc).
  • --help.
  • Log failures.
  • Debug option for printing the wrapped snippet.

Future

• CLI
  • Improve current interface. Jest like interface when running/watching.
• Process code
  • Transpile with Babel. Check for project Babel config. (?)
  • Lint with Eslint. If project has Eslint configured.(?)
• Environment. Use jsdom?
• Snippet metadata. Using MD snippets flags
• Provide a programmatic API.