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

$ npm install -g polymer-lint

Usage

Command line

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

Rules

component-name-matches-filename

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

OK

In a file named foo-component.html:

<dom-module id="foo-component">...</dom-module>

Error

In a file named foo-component.html:

<dom-module id="other-component">...</dom-module>

no-auto-binding

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

OK

<a href="[[val]]">Hello</a>

<p>[[val]]</p>

Error

<a href="{{val}}">Hello</a>

<p>{{val}}</p>

no-missing-import

Ensures that all components that are used have been imported.

Note: This rule does not analyze imported files; it only analyzes <link/> tags and assumes that e.g. <link rel="import" href="foo-component.html"/> will define foo-component.

OK

<link rel="import" href="foo-component.html"/>
<dom-module id="my-component">
  <template>
    <foo-component/>
  </template>
</dom-module>

Error

<dom-module id="my-component">
  <template>
    <foo-component/>
  </template>
</dom-module>

Error

<dom-module id="my-component">
  <template>
    <button is="foo-component">Submit</button>
  </template>
</dom-module>

Error

<dom-module id="my-component">
  <template>
    <style include="my-styles"></style>
  </template>
</dom-module>

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

<link rel="import" href="@polymer/polymer/polymer-element.html"/>
<link rel="import" href="foo-component.html"/>
<dom-module id="my-component">
  <template>
    <foo-component/>
  </template>
</dom-module>

OK

<link rel="import" href="foo-component.html"/>
<dom-module id="my-component">
  <template>
    <button is="foo-component">Submit</button>
  </template>
</dom-module>

OK

<link rel="import" href="my-styles.html"/>
<dom-module id="my-component">
  <template>
    <style include="my-styles"></style>
  </template>
</dom-module>

Error

<link rel="import" href="foo-component.html"/>
<dom-module id="my-component">
  <template>
    <other-component/>
  </template>
</dom-module>

one-component

Ensures that a file defines no more than one component.

OK

<dom-module id="my-component">...</dom-module>

Error

<dom-module id="my-component">...</dom-module>
<dom-module id="another-component">...</dom-module>

style-inside-template

Ensures that no <style> tags appear outside of <template> tags.

OK

<dom-module id="my-component">
  <template>
    <style>/* ... */<style>
    ...
  </template>
</dom-module>

Error

<dom-module id="my-component">
  <style>/* ... */</style>
  <template>...</template>
</dom-module>

no-typeless-buttons

Ensures that a type attribute has been set on <button> or <jha-button> tags.

OK

<button type="submit">...</button>
<button type="button">...</button>
<jha-button type="submit">...</jha-button>
<jha-button type="button">...</jha-button>

Error

<button>...</button>
<jha-button id="someid">...</jha-button>

Linter directives

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

<!-- bplint-directive-name arg1, arg2, ... -->

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:

<dom-module id="my-component">
  <article>
    <mystery-component-1/>
    <!-- bplint-disable no-missing-import -->
    <mystery-component-2/>
  </article>
  <mystery-component-3/>
</dom-module>

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

The polymer-lint output for the above would be:

$ 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:

<dom-module id="my-component">
  <!-- bplint-disable no-missing-import -->
  <mystery-component-1/>
  <!-- bplint-enable no-missing-import -->
  <mystery-component-2/>
</dom-module>

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:

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

✖ 2 errors

Gulp task

See gulp-task/README.md.

Node.js API

API documentation can be generated with JSDoc:

$ 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.

Install

$ git clone [email protected]:Banno/polymer-lint.git
$ cd polymer-lint
$ npm install

Build

To transpile the code:

$ npm run build

Transpiled code will be written to ./lib.

Run with examples

$ ./polymer-lint.js example

Jasmine specs

To run all of the specs:

$ npm test

To run a specific spec file:

$ 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:

$ NODE_PATH=./lib npm test

ESLint

$ npm run lint

Notes

Limitations

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