salesforce-lightning-cli/README.md

# Salesforce Lightning CLI

The Salesforce Lightning CLI is a code review tool that lets you scan your code for Lightning-specific issues. This tool is extremely useful for preparing your Lightning code for the forthcoming LockerService addition to the Lightning Platform.

Lightning CLI is a linting tool based on the open source ESLint project. Like ESLint, it flags issues it finds in your code. Lightning CLI alerts you to specific issues related to LockerService. Issues that are flagged include incorrect Lightning components code, use of unsupported or private Lightning APIs, and a number of general JavaScript coding issues. Lightning CLI installs into the Heroku Toolbelt, and is used on the command line.


## Installation

Lightning CLI relies on Heroku Toolbelt. Make sure you have the `heroku` command installed correctly before attempting to use this tool. More information about Heroku Toolbelt is available here:

https://devcenter.heroku.com/articles/getting-started-with-nodejs#set-up

After getting Heroku Toolbelt up and running, install the Lightning CLI plug-in using the following command:

```bash
heroku plugins:install salesforce-lightning-cli
```

Once installed, the plugin will be updated whenever you update the Heroku Toolbelt using the `heroku update` command. Do this every week or so to make sure you've got the latest Lightning CLI rules.


## Usage

Lightning CLI is run just like any other lint command line tool. The only trick is invoking it through the `heroku` command. Results are output to your shell window.

### Normal Use

You can run the Lightning CLI linter on any folder that contains Lightning components:

```bash
heroku lightning:lint ./path/to/lightning/components/
```

**Note:** The Lightning CLI runs only on local files. Download your component code to your machine using the [Metadata API](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/file_based.htm), or a tool such as the [Force.com IDE](https://developer.salesforce.com/page/Force.com_IDE), the [Force.com Migration Tool](https://developer.salesforce.com/page/Force.com_Migration_Tool), or any of a number of third-party options.

### Filtering Files

Sometimes you just want to scan a particular kind of file. The `--files` argument allows you to set a pattern to match files against.

For example, the following command allows you to scan controllers only:

```bash
heroku lightning:lint ./path/to/lightning/components/ --files **/*Controller.js
```

### Include Warnings

By default only errors will be output from the Lightning CLI. The `--verbose` argument will also output any warning message during the linting process.

### Custom "House Style" Rules

It's common that different organizations or projects will adopt different JavaScript rules. The Lightning CLI tool is here to help you get ready for LockerService, not enforce salesforce.com coding conventions. To that end, the Lightning CLI rules are divided into two sets, security rules and style rules. The security rules can't be modified, but you can modify or add to the style rules.

Use the `--config` argument to provide a custom rules configuration file. A custom rules configuration file allows you to define your own code style rules, which affect the **style** rules used by the Lightning CLI tool.

The Lightning CLI default style rules are defined in `lib/code-style-rules.js` inside this package. Make a copy of that file, and modify it to match your existing ESLint style rules. Alternatively, you can use your existing ESLint rule configuration file directly. For example:

```bash
heroku lightning:lint ./path/to/lightning/components/ --config ~/.eslintrc
```

**Note:** Not all ESLint rules can be added or modified using --config. Only rules that we consider benign or neutral in the context of Lightning Platform are activated by Lightning CLI. And again, you can't override the security rules.


## Results

When you run Lightning CLI on your Lightning components code, the tool outputs results for each file scanned.

```bash
error     secure-document    Invalid SecureDocument API
Line:109:29
        scrapping = document.innerHTML;
                             ^

warning   no-plusplus   Unary operator '++' used
Line:120:50
        for (var i = (index+1); i < sibs.length; i++) {
                                                 ^

error    secure-window  Invalid SecureWindow API
Line:33:21
        var req = new XMLHttpRequest();
                  ^

error  default-case  Expected a default case
Line:108:13
            switch (e.keyCode) {
            ^
```

Issues are displayed, one for each warning or error. Each issue includes the line number, severity, and a brief description of the issue. It also includes the rule name, which you can use to look up a more detailed description of the issue in the Lightning CLI documentation or ESLint documentation, as well as possible resolutions and options for further reading.

Your mission is to review each issue, examine the code in question, and to revise it to eliminate all of the genuine problems.

While no automated tool is perfect, we expect that most errors and warnings generated by Lightning CLI will point to genuine issues in your code, which you should plan to fix before using it with LockerService enabled.


## Getting Help

Lightning CLI also provides some built-in help, which you can access at any time with the following commands:

```bash
heroku lightning --help
heroku lightning:lint --help
```


## License

The [Salesforce Developer MSA](http://www.sfdcstatic.com/assets/pdf/misc/salesforce_Developer_MSA.pdf) governs your use of the Lightning CLI.