leasot/README.md

![leasot](media/leasot.png)

> Parse and output TODOs and FIXMEs from comments in your files

[![NPM Version](http://img.shields.io/npm/v/leasot.svg?style=flat)](https://npmjs.org/package/leasot)
[![NPM Downloads](http://img.shields.io/npm/dm/leasot.svg?style=flat)](https://npmjs.org/package/leasot)
[![Build Status](http://img.shields.io/travis/pgilad/leasot.svg?style=flat)](https://travis-ci.org/pgilad/leasot)

Easily extract, collect and report TODOs and FIXMEs in your code. This project uses regex in order
to extract your todos from comments.

![Basic output example of leasot](media/table.png)

## Comment format

`TODO: add some info`

- Spaces are optional.
- Colon is optional.
- Must be in a comment (line or block) in its' own line (`some code(); //TODO: do something` is not supported).
- Can be prefixed with a @ (i.e @TODO).
- Spaces are trimmed around comment text.
- Supported default types are `TODO` and `FIXME` - case insensitive.
- Additional types can be added (using `tags` in cli and `customTags` in `leasot.parse`)
- New extensions can be associated with bundled parsers as many languages have overlapping syntax

## Supported languages:

| Filetype     | Extension            | Notes                              | Parser Name         |
| ------------ | -------------------- | -----------------------------------| ------------------- |
| C#           | `.cs`                | Supports `// and /* */` comments.  | defaultParser       |
| C++/C        | `.cpp` `.c` `.h`     | Supports `// and /* */` comments.  | defaultParser       |
| CSS          | `.css`               | Supports `/* */` comments.         | defaultParser       |
| Coffee-React | `.cjsx`              | Supports `#` comments.             | coffeeParser        |
| Coffeescript | `.coffee`            | Supports `#` comments.             | coffeeParser        |
| EJS          | `.ejs`               | Supports `<!-- -->` and `<%# %>`   | ejsParser           |
| Erb          | `.erb`               | Supports `<!-- -->`                | twigParser          |
| Erlang       | `.erl` `.hrl`        | Supports `%` comments.             | erlangParser        |
| Go           | `.go`                | Supports `// and /* */` comments.  | defaultParser       |
| HTML         | `.html` `.htm`       | Supports `<!-- -->`                | twigParser          |
| Haml         | `.haml`              | Supports `/ -# <!-- --> and <%# %>`| twigParser          |
| Handlebars   | `.hbs` `.handlebars` | Supports `{{! }}` and `{{!-- --}}` | hbsParser           |
| Haskell      | `.hs`                | Supports `--`                      | haskellParser       |
| Hogan        | `.hgn` `.hogan`      | Supports `{{! }}` and `{{!-- --}}` | hbsParser           |
| Jade         | `.jade`              | Supports `//` and `//-` comments.  | jadeParser          |
| Javascript   | `.js` `.es` `.es6`   | Supports `// and /* */` comments   | defaultParser       |
| Jsx          | `.jsx`               | Supports `// and /* */` comments.  | defaultParser       |
| Less         | `.less`              | Supports `// and /* */` comments.  | defaultParser       |
| Mustache     | `.mustache`          | Supports `{{! }}` and `{{!-- --}}` | hbsParser           |
| PHP          | `.php`               | Supports `// and /* */` comments.  | defaultParser       |
| Pascal       | `.pas`               | Supports `// and { }` comments.    | pascalParser        |
| Perl         | `.pl`, `.pm`         | Supports `#` comments.             | coffeeParser        |
| Python       | `.py`                | Supports `"""` and `#` comments.   | pythonParser        |
| Ruby         | `.rb`                | Supports `#` comments.             | coffeeParser        |
| Sass         | `.sass` `.scss`      | Supports `// and /* */` comments.  | defaultParser       |
| Shell        | `.sh` `.zsh` `.bash` | Supports `#` comments.             | coffeeParser        |
| SilverStripe | `.ss`                | Supports `<%-- --%>` comments.     | ssParser            |
| Stylus       | `.styl`              | Supports `// and /* */` comments.  | defaultParser       |
| Twig         | `.twig`              | Supports `{#  #}` and `<!-- -->`   | twigParser          |
| Typescript   | `.ts`                | Supports `// and /* */` comments.  | defaultParser       |

Javascript is the default parser.

**PRs for additional filetypes is most welcomed!!**

## Usage

### Command Line

#### Installation

```sh
$ npm install --global leasot
```

#### Examples

```sh
❯ leasot --help

  Usage: leasot [options] <file ...>

  Parse and output TODOs and FIXMEs from comments in your files

  Options:

    -h, --help                           output usage information
    -V, --version                        output the version number
    -r, --reporter [reporter]            use reporter (table|json|xml|markdown|raw) (default: table)
    -t, --filetype [filetype]            force the filetype to parse. Useful for streams (default: .js)
    -T, --tags <tags>                    add additional comment types to find (alongside todo & fixme)
    -S, --skip-unsupported               skip unsupported filetypes
    -I, --inline-files                   parse possible inline files
    -A, --associate-parser [ext,parser]  associate unknown extensions with bundled parsers (parser optional / default: defaultParser)

  Examples:

    # Check a specific file
    $ leasot index.js

    # Check php files with glob
    $ leasot **/*.php

    # Check multiple different filetypes
    $ leasot app/**/*.js test.rb

    # Use the json reporter
    $ leasot --reporter json index.js

    # Search for REVIEW comments as well
    $ leasot --tags review index.js

    # Export TODOS as markdown to a TODO.md file
    $ leasot --reporter markdown app/**/*.py > TODO.md

    # Check a stream specifying the filetype as coffee
    $ cat index.coffee | leasot --filetype .coffee
```

### Programmatic

#### Installation

```sh
$ npm install --save-dev leasot
```

#### Examples

```js
var fs = require('fs');
var leasot = require('leasot');

var contents = fs.readFileSync('./contents.js', 'utf8');
// get the filetype of the file, or force a special parser
var filetype = path.extname('./contents.js');
// add file for better reporting
var file = 'contents.js';
var todos = leasot.parse({ext: filetype,content: contents,fileName: file});

// -> todos now contains the array of todos/fixme parsed

var output = leasot.reporter(todos, {
    reporter: 'json',
    spacing: 2
});

console.log(output);
// -> json output of the todos
```

### Build Time

* [gulp-todo](https://github.com/pgilad/gulp-todo)
* [broccoli-leasot](https://github.com/sivakumar-kailasam/broccoli-leasot)

## API

```js
var leasot = require('leasot');
```

`leasot` exposes the following API:

### .associateExtWithParser(parsers)

Associates a bundled parser with a new extension.

The `parsers` parameter must be completed in the following format:

```js
{
    '.cls': {
        parserName: 'defaultParser'
    }
}
```

### .isExtSupported(extension)

Check whether extension is supported by parser.

Specify an extension including the prefixing dot, for example:

`leasot.isExtSupported('.js'); //-> true`

**Returns**: `Boolean`

### .parse(options)

| Name                | Type       | Required | Default | Description                                           |
| ----                | ----       | -------- | ------- | -----------                                           |
| `ext`               | `string`   | Yes      |         | The extension the parse as including a prefixing dot. |
| `content`           | `string`   | Yes      |         | Content to parse                                      |
| `fileName`          | `string`   | No       |         | fileName to attach to todos output                    |
| `customTags`        | `array`    | No       | `[]`    | Additional tags (comment types) to search for (alongside todo & fixme) |
| `withIncludedFiles` | `boolean`  | No       | `false` | Parse also possible included file types (for example: `css` inside a `php` file |
| `associateParser`   | `object`   | No       |         | See `.associateExtWithParser` for syntax              |

**Returns**: `array` of comments.

```js
[{
    file: 'parsedFile.js',
    text: 'comment text',
    kind: 'TODO',
    line: 8
}]
```

### .reporter(comments, config)

Use the specified reporter to report the comments.

`comments` is the array of comments received from `leasot.parse()`.

`config` is an object that will also be passed to the reporter itself (allowing custom options for each reporter).

It may also contain the specified reporter:

#### config.reporter

Can be a string indicating the [built-in reporter](#built-in-reporters) to use,
 or an external library used as a reporter.

Could also be a custom function `(comments, config)`

**Type**: `String|Function`

**Required**: `false`

**Default**: `raw`

## Built-in Reporters

- json
- xml
- raw
- table
- markdown

Each reporter might contain config params that are useful only for that reporter:

### Markdown

Returns a markdown version of the todos.

### Options

#### newLine

How to separate lines in the output file. Defaults to your OS's default line separator.

**Type**: `String`

**Default**: `Your system default line feed`

### padding

How many `newLine`s should separate between comment type blocks.

**Type**: `Number`

**Default**: `2`

**Minimum**: `0`

### transformHeader(kind)

Control the output of a header for each comment kind (*i.e todo, fixme*).

**Type**: `Function`

**Default**:
```js
transformHeader: function (kind) {
    return ['### ' + kind + 's',
        '| Filename | line # | ' + kind,
        '|:------|:------:|:------'
    ];
}
```

**kind**: will be be passed as the comment kind (todo/fixme).

**Returns**: `String[]|String`

You are expected to return either an `Array of strings` or just a `string`. If you return an array - each item will be separated by a newline in the output.

### transformComment(file, line, text, kind)

Control the output for each comment.

**Type**: `Function`

**Default**:
```js
transformComment: function (file, line, text, kind) {
    return ['| ' + file + ' | ' + line + ' | ' + text];
},
```

**file**: filename the comment was in.

**line**: line of comment.

**text**: comment text

**kind**: will be be passed as the comment kind (todo/fixme).

**Returns**: `String[]|String`

You are expected to return either an `Array of strings` or just a `string`. If you return an array - each item will be separated by a newline in the output.

### Table

Returns a pretty formatted table of the todos.

### Raw

Just returns the raw javascript todos

### JSON

Return a JSON valid representation of the todos.

#### Options

##### spacing

Type: `Number`

Default: `2`

### XML

Return an unformatted XML valid representation of the todos.

Parsed using [json2xml](https://github.com/estheban/node-json2xml)

#### Options

##### header

Whether to include xml header

Type: `Boolean`

Default: `true`

##### attributes_key

See https://github.com/estheban/node-json2xml#options--behaviour

Type: `Boolean`

Default: `undefined`

## License

MIT ©[Gilad Peleg](http://giladpeleg.com)