polymer-lint

polymer-lint
============

A linter for Polymer components

Table of Contents
-----------------
- Installation
- Usage
- Command line
- Rules
- component-name-matches-filename
- no-auto-binding
- no-missing-import
- no-unused-import
- one-component
- style-inside-template
- Linter directives
- Gulp task
- Node.js API
- Configuration
- Development
- Notes
- TODO

Installation
------------

``sh
$ npm install -g polymer-lint
`

Usage
-----

$3

`text
polymer-lint [options] file.html [file.html] [dir]

--ext [String] File extension(s) to lint - default: .html
--rules [String] Names of rules to enable; defaults to all rules
--color, --no-color Force enabling/disabling of color
-h, --help Show help
-v, --version Output the version number
`

$3

#### component-name-matches-filename

Ensures that the component defined in a file matches its filename.

###### OK

In a file named foo-component.html:

`html
...
`

###### Error

In a file named foo-component.html:

`html
...
`

#### no-auto-binding

Ensures that only one-way bindings ([[val]]) are used.

###### OK

`html
Hello
`

`html


[[val]]


`

###### Error

`html
Hello
`

`html


{{val}}


`

#### no-missing-import

Ensures that all components that are used have been imported.

Note: This rule does not analyze imported files; it only analyzes
tags and assumes that e.g. will
define foo-component.

###### OK

`html




`

###### Error

`html



`

###### Error

`html



`

###### Error

`html



`

#### no-unused-import

Ensures that all components that are imported are used.

This rule assumes that imported filenames match the names of the elements they
define, and ignores imports for names that don't end with .html or aren't
valid custom element names. It also ignores the filename polymer-element.html.

###### OK

`html





`

###### OK

`html




`

###### OK

`html




`

###### Error

`html




`

#### one-component

Ensures that a file defines no more than one component.

###### OK

`html
...
`


###### Error

`html
...
...
`

#### style-inside-template

Ensures that no


`

#### no-typeless-buttons

Ensures that a type attribute has been set on or tags.

###### OK

`html


...
...
...
...
`

###### Error

`html
...
...
`

$3

Component code can give instructions to the Linter via directives, which
are HTML comments of the form:

`text

`

#### bplint-disable

The bplint-disable directive tells the linter to ignore errors
reported by the given rules from this point on, within the current
scope. For example:

`html












`

None of the three elements has been imported,
but the bplint-disable directive ensures that errors will only be
reported for (because it's before the
directive) and (because it's outside the scope
in which the bplint-disable directive was used.

The polymer-lint output for the above would be:

`text
$ polymer-lint my-component.html
my-component.html
3:5 Custom element 'mystery-component-1' used but not imported no-missing-import
7:3 Custom element 'mystery-component-3' used but not imported no-missing-import

✖ 2 errors
`

#### bplint-enable

The bplint-enable directive negates the action of the bplint-disable
directive from this point on, within the current scope. For example:

`html






`

Neither mystery-component-1 nor mystery-component-2 has been imported, but
an error will be reported only for mystery-component-2. The polymer-lint
output for the above would be:

`text
$ polymer-lint my-component.html
my-component.html
5:3 Custom element 'mystery-component-2' used but not imported no-missing-import

✖ 2 errors
`




$3

See gulp-task/README.md.

$3

API documentation can be generated with JSDoc:

`sh
$ npm install -g jsdoc
$ jsdoc -c ./jsdoc.json
$ open doc/index.html
`

Configuration
-------------
At present configuration is only possible via command-line arguments
or the Node.js API.

Development
-----------

Note: At present, development requires Node.js v6.0.0 or greater.

$3

`sh
$ git clone git@github.com:Banno/polymer-lint.git
$ cd polymer-lint
$ npm install
`

$3

To transpile the code:

`sh
$ npm run build
`

Transpiled code will be written to ./lib.

$3

`sh
$ ./polymer-lint.js example
`

$3

To run all of the specs:

`sh
$ npm test
`

To run a specific spec file:

`sh
$ npm test spec/lib/mySpec.js
`

By default the specs will run tests against the pre-transpiler code in ./src.
To run the tests against the transpiled code (i.e. after npm run build), set
the NODE_PATH environment variable:

`sh
$ NODE_PATH=./lib npm test
`

$3

`sh
$ npm run lint
`

Notes
-----


$3

polymer-lint currently has the following limitations:

* Only HTML code is linted. JavaScript code is not analyzed.
* The polymer-lint command cannot read from STDIN.
* The polymer-lint` command can only be configured via command line
arguments; it cannot read from a configuration file.

TODO
----
* Windows support
* Read configuration from file
* Grunt task
* Put API docs online
* Editor integrations