mop-cli
Version:
Lint and maintain many projects at once
239 lines (137 loc) • 5.97 kB
Markdown
# mop-cli [](https://circleci.com/gh/sholladay/mop-cli "Builds")
> Lint and maintain many projects at once
Like [ESLint](https://eslint.org) for your entire computer and more than just JavaScript.
## Contents
- [Why?](#why)
- [Install](#install)
- [Usage](#usage)
- [Rules](#rules)
- [Data Types](#data-types)
- [API](#api)
- [Tips](#tips)
- [FAQ](#faq)
- [Related](#related)
- [Contributing](#contributing)
- [License](#license)
## Why?
- Some of us have a lot of modules.
- We often want to change multiple modules simultaneously.
- Helps you scale and keep track of todos across projects.
- Easy maintenance means happy developers and users.
## Install
```sh
npm install mop-cli --global
```
## Usage
```console
$ mop --help
Usage
$ mop [rule-name]
Option
--cwd Working directory to search for projects
--reporter How to display and stylize results
Example
$ mop caret-deps
$ mop caret-deps --reporter=eslint
```
*Tip: On Node < 7.6, `mop` needs to be `node --harmony "$(which mop)"`*
## Rules
See the [list of rules](doc/README.md) to change what triggers `mop` to complain.
## Data types
### Project
A project is an object with `name`, `path` and `pkg` properties.
#### name
Type: `string`
Either `pkg.name` if it is available or the [basename](https://nodejs.org/api/path.html#path_path_basename_path_ext) of the project's `path`.
#### path
Type: `string`
Filepath of the project's root directory.
#### pkg
Type: `object`, `null`
Parsed package.json found within `path`, or `null` if the file is missing. An error will be thrown if the file is present but cannot be read or is invalid.
---
**Projects are enhanced with the following properties before they are returned to users.**
#### problems
Type: `Array<Problem>`
A list of all rule violations the project is responsible for.
#### errors
Type: `Array<Problem>`
Same as `problems`, but only those whose `severity` is `error`.
#### warnings
Type: `Array<Problem>`
Same as `problems`, but only those whose `severity` is `warn`.
### Problem
Each rule may optionally return a problem descriptor, which represents a rule violation. The only required property is `message`.
#### message
Type: `string`
A message describing the problem.
#### path
Type: `string`
Filepath that is responsible for the problem.
#### line
Type: `number`
A positive, zero-based integer within the file where the problem occurred.
#### column
Type: `number`
A positive, zero-based integer within the line where the problem occurred.
#### data
Type: any
Arbitrary data that reporters can use to enhance output.
---
**Problems are enhanced with the following properties before they are returned to users.**
#### ruleId
Type: `string`
The rule that reported the problem.
#### severity
Type: `string`<br>
Example: `warn`
The problem level, as configured by the user for the rule.
### rule(project, ...args)
Returns a [problem](#problem) or an `Array` of problems, optionally wrapped in a `Promise`, if the project violates the expectations of the rule.
Learn more about rules by [creating one](doc/README.md#creating-rules).
#### project
Type: `object`
A [project](#project) for the rule to check.
#### args
Custom arguments for the rule provided by the user in their configuration. Most rules that use this accept just a single `option` object with properties for configuring the rule.
## API
### mop(option)
Returns a `Promise` for an `Array` of [project](#project) results with lists of rule violations.
### option
#### cwd
Type: `string`<br>
Default: `process.cwd()`
Final directory in a downwards search for projects. Only used when no `projects` are provided.
#### projects
Type: `Array<Project>`
List of [projects](#project) to lint.
#### rule
Type: `object`
Map of rules to apply and their arguments. Compatible with [ESLint conventions](https://eslint.org/docs/user-guide/configuring#configuring-rules).
Example:
```js
{
'caret-deps' : 'warn',
foo : ['error', 'blah']
}
```
## Tips
### Enable rules gently
Because Mop checks many projects at once, enabling a single rule can cause many more errors to be reported than in tools like ESLint that check a single project. THis is good, as it gives you a high level view of where fixes are needed. However, when you are initially configuring Mop, you should enable rules one at a time in order to avoid being overwhelmed.
## FAQ
### How is this different than ESLint?
Mop checks every project it can find, whereas ESLint only checks a single project. Mop also doesn't care what language you use, although it is optimized for JavaScript projects. It is actually more like [clinton](https://github.com/SamVerschueren/clinton) than ESLint, but people are more familiar with ESLint, hence the comparison.
## Related
- [clinton](https://github.com/SamVerschueren/clinton) - Project style linter for individual projects
- [XO](https://github.com/sindresorhus/xo) - JavaScript linter for individual projects
- [Stylelint](https://github.com/stylelint/stylelint) - CSS linter for individual projects
## Contributing
See our [contributing guidelines](https://github.com/sholladay/mop-cli/blob/master/CONTRIBUTING.md "Guidelines for participating in this project") for more details.
1. [Fork it](https://github.com/sholladay/mop-cli/fork).
2. Make a feature branch: `git checkout -b my-new-feature`
3. Commit your changes: `git commit -am 'Add some feature'`
4. Push to the branch: `git push origin my-new-feature`
5. [Submit a pull request](https://github.com/sholladay/mop-cli/compare "Submit code to this project for review").
## License
[MPL-2.0](https://github.com/sholladay/mop-cli/blob/master/LICENSE "License for mop-cli") © [Seth Holladay](https://seth-holladay.com "Author of mop-cli")
Go make something, dang it.