1 | <h1 align="center">
|
2 | <br>
|
3 | <br>
|
4 | <img width="320" src="media/leasot.png" alt="Leasot">
|
5 | <br>
|
6 | <br>
|
7 | <br>
|
8 | Leasot
|
9 | </h1>
|
10 |
|
11 | > Intelligently parse and output TODOs and FIXMEs from comments in your files
|
12 |
|
13 | [![npm](https://img.shields.io/npm/v/leasot.svg?style=for-the-badge)](https://www.npmjs.com/package/leasot)
|
14 | [![npm downloads](https://img.shields.io/npm/dm/leasot.svg?style=for-the-badge)](https://www.npmjs.com/package/leasot)
|
15 | [![Travis (.org)](https://img.shields.io/travis/pgilad/leasot.svg?style=for-the-badge)](https://travis-ci.org/pgilad/leasot)
|
16 | [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=for-the-badge)](https://github.com/prettier/prettier)
|
17 |
|
18 | Easily extract, collect and report TODOs and FIXMEs in your code. This project uses regex in order
|
19 | to extract your todos from comments.
|
20 |
|
21 | ![Basic output example of leasot](media/table.png)
|
22 |
|
23 | ## Comment format
|
24 |
|
25 | `TODO: add some info`
|
26 |
|
27 | - Spaces are optional.
|
28 | - Colon is optional.
|
29 | - Must be in a comment (line or block) in its' own line (`some code(); //TODO: do something` is not supported).
|
30 | - Can be prefixed with a @ (i.e @TODO).
|
31 | - Spaces are trimmed around comment text.
|
32 | - Supported default types are `TODO` and `FIXME` - case insensitive.
|
33 | - Additional types can be added (using `tags` in cli and `customTags` in `leasot.parse`)
|
34 | - New extensions can be associated with bundled parsers as many languages have overlapping syntax
|
35 | - Supports both leading and trailing references. Examples:
|
36 | - `// TODO(tregusti): Make this better`
|
37 | - `// TODO: Text /tregusti`
|
38 |
|
39 | ## Supported languages
|
40 |
|
41 | [49+ languages are supported](./media/supported-languages.md), pull requests for additional language support is most welcomed!
|
42 |
|
43 | ## Usage in command line
|
44 |
|
45 | ```bash
|
46 | npm install --global leasot
|
47 | ```
|
48 |
|
49 | ## Command line help
|
50 |
|
51 | ```bash
|
52 | $ leasot --help
|
53 |
|
54 | Usage: leasot [options] <file ...>
|
55 |
|
56 | Parse and output TODOs and FIXMEs from comments in your files
|
57 |
|
58 | Options:
|
59 | -V, --version output the version number
|
60 | -A, --associate-parser [ext,parser] associate unknown extensions with bundled parsers (parser optional / default: defaultParser) (default: {})
|
61 | -i, --ignore <patterns> add ignore patterns (default: [])
|
62 | -I, --inline-files parse possible inline files (default: false)
|
63 | -r, --reporter [reporter] use reporter (table|json|xml|markdown|vscode|raw) (default: table) (default: "table")
|
64 | -S, --skip-unsupported skip unsupported filetypes (default: false)
|
65 | -t, --filetype [filetype] force the filetype to parse. Useful for streams (default: .js)
|
66 | -T, --tags <tags> add additional comment types to find (alongside todo & fixme) (default: [])
|
67 | -x, --exit-nicely exit with exit code 0 even if todos/fixmes are found (default: false)
|
68 | -h, --help output usage information
|
69 |
|
70 | Examples:
|
71 | # Check a specific file
|
72 | $ leasot index.js
|
73 |
|
74 | # Check php files with glob
|
75 | $ leasot '**/*.php'
|
76 |
|
77 | # Check multiple different filetypes
|
78 | $ leasot 'app/**/*.js' test.rb
|
79 |
|
80 | # Use the json reporter
|
81 | $ leasot --reporter json index.js
|
82 |
|
83 | # Search for REVIEW comments as well
|
84 | $ leasot --tags review index.js
|
85 |
|
86 | # Add ignore pattern to filter matches
|
87 | $ leasot 'app/**/*.js' --ignore '**/custom.js'
|
88 |
|
89 | # Search for REVIEW comments as well
|
90 | $ leasot --tags review index.js
|
91 |
|
92 | # Check a stream specifying the filetype as coffee
|
93 | $ cat index.coffee | leasot --filetype .coffee
|
94 |
|
95 | # Report from leasot parsing and filter todos using `jq`
|
96 | $ leasot 'tests/**/*.styl' --reporter json | jq 'map(select(.tag == "TODO"))' | leasot-reporter
|
97 |
|
98 | # Associate a parser for an unknown extension`
|
99 | $ leasot -A '.svelte,twigParser' -A '.svelte,defaultParser' 'frontend/*.svelte'
|
100 | ```
|
101 |
|
102 | ### Usage in NPM scripts
|
103 |
|
104 | Use `leasot -x` in order to prevent exiting with a non-zero exit code. This is a good solution if you plan to
|
105 | run `leasot` in a CI tool to generate todos.
|
106 |
|
107 | ```json
|
108 | {
|
109 | "scripts": {
|
110 | "todo": "leasot 'src/**/*.js'",
|
111 | "todo-ci": "leasot -x --reporter markdown 'src/**/*.js' > TODO.md"
|
112 | },
|
113 | "devDependencies": {
|
114 | "leasot": "^7.0.0"
|
115 | }
|
116 | }
|
117 | ```
|
118 |
|
119 | ### Programmatic Installation
|
120 |
|
121 | ```bash
|
122 | npm install --save-dev leasot
|
123 | ```
|
124 |
|
125 | ### Programmatic Examples
|
126 |
|
127 | ```js
|
128 | const fs = require('fs');
|
129 | const leasot = require('leasot');
|
130 |
|
131 | const contents = fs.readFileSync('./contents.js', 'utf8');
|
132 | // get the filetype of the file, or force a special parser
|
133 | const filetype = path.extname('./contents.js');
|
134 | // add file for better reporting
|
135 | const file = 'contents.js';
|
136 | const todos = leasot.parse(contents, { extension: filetype, filename: file });
|
137 |
|
138 | // -> todos now contains the array of todos/fixme parsed
|
139 |
|
140 | const output = leasot.report(todos, 'json', { spacing: 2 });
|
141 |
|
142 | console.log(output);
|
143 | // -> json output of the todos
|
144 | ```
|
145 |
|
146 | ### Leasot with build tools
|
147 |
|
148 | - [gulp-todo](https://github.com/pgilad/gulp-todo)
|
149 | - [broccoli-leasot](https://github.com/sivakumar-kailasam/broccoli-leasot)
|
150 | - [todo-webpack-plugin](https://github.com/mikeerickson/todo-webpack-plugin)
|
151 |
|
152 | ## API
|
153 |
|
154 | ```js
|
155 | const leasot = require('leasot');
|
156 | ```
|
157 |
|
158 | See [main exported functions](src/index.ts)
|
159 |
|
160 | Mainly, you should be using 2 functions:
|
161 |
|
162 | - [parse](https://pgilad.github.io/leasot/index.html#parse) for parsing file contents
|
163 | - [report](https://pgilad.github.io/leasot/index.html#report) for reporting the todos
|
164 |
|
165 | [Type documentation](https://pgilad.github.io/leasot)
|
166 |
|
167 | ## Built-in Reporters
|
168 |
|
169 | See [built-in reporters](https://pgilad.github.io/leasot/enums/builtinreporters.html)
|
170 |
|
171 | ## License
|
172 |
|
173 | MIT © [Gilad Peleg](https://www.giladpeleg.com)
|