Docs: troubleshooting and toc (#40)

* fix: lock @typescript-eslint/eslint-plugin version
in range minor version of @typescript-eslint/eslint-plugin breaks its utils

* ci: ignore built and dependecies files

* chore: add table of contents and fix commit hook

* docs: add troubleshooting note

* docs: fix lint-staged example and add note about "git add"

* chore: restrict using `npm i` in root

* chore: fix tagging for prerelease

.eslintignore

@@ -1,3 +1,5 @@
 *.fixture.*
 packages/linters/tslint/rules
 packages/linters/tslint/src
+node_modules
+dist

.lintstagedrc.js

@@ -0,0 +1,9 @@
+module.exports = {
+    'packages/**/*.{ts,js}': ['eslint --fix'],
+    '**/README.md': [
+        files => files.map(file => `markdown-toc -i ${file}`), // single file per command
+        'prettier --write',
+        'git add' // fixes 'Changes not staged for commit'
+    ],
+    '**/*.{md,json,template.html}': ['prettier --write --loglevel=warn']
+}

CONTRIBUTING.md

@@ -0,0 +1,19 @@
+## Development
+
+-   Intall deps with `npm run bootstrap`.
+-   Run tests with `npm run test:ci`.
+-   Follow [Conventional Commits specification](https://conventionalcommits.org/) for every commitmessage.
+
+## Release
+
+-   Prepare your release into `master` or `release/*` branch.
+-   Run `npm run version` and look what happens.
+    -   Or `npm run version -- --no-push` and `git push --follow-tags` you are not sure.
+-   Run `npm run publish`.
+
+**Pre-release:**
+
+Do the same as above, except this cases:
+
+-   prev version isn't prerelease, but next must be prerelease: `npm run version -- --conventional-prerelease`
+-   prev version is prerelease, but next must be release: `npm run version -- --conventional-graduate`

README.md

@@ -2,10 +2,33 @@
 
 This repository contains configuration files for the linters we use in Tinkoff. It includes:
 
--   configs and rules for [TSLint](https://palantir.github.io/tslint/)
+-   configs and rules for [ESLint](https://eslint.org/)
+-   configs and rules for [TSLint](https://palantir.github.io/tslint/) <small>(deprecated)</small>
 -   configs for [Stylelint](https://stylelint.io/)
 -   configs for [Prettier](https://prettier.io)
--   configs for [ESLint](https://eslint.org/)
+
+## Table of Contents
+
+<!-- toc -->
+
+-   [Install](#install)
+-   [ESLint + Prettier](#eslint--prettier)
+-   [Stylelint](#stylelint)
+-   [Husky + lint-staged (recomended)](#husky--lint-staged-recomended)
+-   [TSLint (deprecated)](#tslint-deprecated)
+-   [VS Code](#vs-code)
+-   [Troubleshooting](#troubleshooting)
+    -   [`0:0 error Parsing error: File '/…/myProjectRoot/tsconfig.json' not found`](#00-error-parsing-error-file-myprojectroottsconfigjson-not-found)
+    -   [`Parsing error: "parserOptions.project" has been set for @typescript-eslint/parser.`](#parsing-error-parseroptionsproject-has-been-set-for-typescript-eslintparser)
+-   [Custom rules for TSLint](#custom-rules-for-tslint)
+    -   [`tinkoff-angular-member-ordering`](#tinkoff-angular-member-ordering)
+    -   [`tinkoff-condition-breaks`](#tinkoff-condition-breaks)
+    -   [`tinkoff-method-return-type`](#tinkoff-method-return-type)
+    -   [`tinkoff-new-line-after-variable-declaration`](#tinkoff-new-line-after-variable-declaration)
+    -   [`tinkoff-new-line-around-control-statement`](#tinkoff-new-line-around-control-statement)
+-   [Badge](#badge)
+
+<!-- tocstop -->
 
 ## Install
 
@@ -42,7 +65,7 @@ For now there is additional `angular` rules available, and we planning to add `R
 
 Add following files in your project:
 
-##### **`.eslintrc.js`**
+**`.eslintrc.js`**
 
 ```js
 module.exports = {
@@ -53,7 +76,7 @@ module.exports = {
 };
 ```
 
-##### **`.prettierrc.js`**
+**`.prettierrc.js`**
 
 ```js
 module.exports = {
@@ -81,7 +104,7 @@ Add `.eslintignore` file.
 
 You need to use different base config:
 
-##### **`.eslintrc.js`**
+**`.eslintrc.js`**
 
 ```js
 module.exports = {
@@ -92,7 +115,7 @@ module.exports = {
 };
 ```
 
-##### **`.prettier.config.js`**
+**`.prettier.config.js`**
 
 ```js
 module.exports = {
@@ -111,25 +134,11 @@ Add npm-script:
 
 </details>
 
-<details>
-    <summary>Troubleshooting</summary>
-
-If you're got this error:
-
-```
-Parsing error: "parserOptions.project" has been set for @typescript-eslint/parser.
-```
-
--   Make sure that `.ts`/`.tsx` file mentioned in this error is included in your projects `./tsconfig.json`
--   OR Update config: ##### **`.eslintrc.js`**
-    `diff module.exports = { extends: [ './node_modules/@tinkoff/linters/eslint/base', './node_modules/@tinkoff/linters/eslint/angular', ], + parserOptions: { + createDefaultProgram: true, // Allows to work with non-ts files + }, }` > `createDefaultProgram` may cause [performance issues](https://github.com/typescript-eslint/typescript-eslint/blob/master/packages/parser/README.md#configuration)
-    </details>
-
 ## Stylelint
 
 You should extend your Stylelint configs with only one `bases` config:
 
-##### **`.stylelintrc`**
+**`.stylelintrc`**
 
 ```json
 {
@@ -144,13 +153,13 @@ Add npm-script:
     "lint:less:ci": "stylelint --config .stylelintrc --custom-formatter=node_modules/stylelint-teamcity-reporter \"src/**/*.less\"",
 ```
 
-## Husky + lint-staged
+## Husky + lint-staged (recomended)
 
 ```sh
 $ npm i husky lint-staged --save-dev
 ```
 
-##### **`.huskyrc.json`**
+**`.huskyrc.json`**
 
 ```js
 {
@@ -160,16 +169,18 @@ $ npm i husky lint-staged --save-dev
 }
 ```
 
-##### **`.lintstagedrc.json`**
+**`.lintstagedrc.json`**
 
 ```js
 {
-    "src/**/*.{ts,js}": ["lint:es", "git add"],
+    "src/**/*.{ts,js}": ["eslint --fix", "git add"],
     "src/**/*.less": ["prettier --write", "lint:less", "git add"],
     "src/**/*.{md,json,template.html}": ["prettier --write", "git add"]
 }
 ```
 
+> You dont have to add trailing `git add` when using `lint-staged@10+`. [See in its docs](https://github.com/okonet/lint-staged/blob/f9e128d/README.md#reformatting-the-code).
+
 ## TSLint (deprecated)
 
 TSLint no longer supported. See [roadmap](/ROADMAP.md).
@@ -209,6 +220,44 @@ To make eslint work with `.ts` files:
     ]
     ```
 
+## Troubleshooting
+
+### `0:0 error Parsing error: File '/…/myProjectRoot/tsconfig.json' not found`
+
+By default `tsconfig.json` is expected in the same root folder as `.eslintrc.js`.
+If you have `tsconfig.json` somewhere in your subfolder you must create additional `.eslintrc.js` in the same folder with your `tsconfig.json`.
+**`.eslintrc.js`**
+
+```js
+module.exports = {
+    parserOptions: {
+        tsconfigRootDir: __dirname,
+    },
+};
+```
+
+### `Parsing error: "parserOptions.project" has been set for @typescript-eslint/parser.`
+
+-   Make sure that you have `.ts[x]` file from the error is included in your root `./tsconfig.json`.
+    -   If you dont want to include all `.ts` files in root config then read previous tip.
+-   OR Update config: <br/>
+    **`.eslintrc.js`**
+    ```diff
+    module.exports = {
+        extends: [
+            './node_modules/@tinkoff/linters/eslint/base',
+            './node_modules/@tinkoff/linters/eslint/angular',
+        ],
+    +    parserOptions: {
+    +        createDefaultProgram: true, // Allows to work with non-ts files
+    +    },
+    }
+    ```
+    > `createDefaultProgram` may cause [performance issues](https://github.com/typescript-eslint/typescript-eslint/blob/master/packages/parser/README.md#configuration)
+
+<br />
+<br />
+-----
 <br />
 <br />
 
@@ -338,23 +387,3 @@ Show that you use `@tinkoff/linters` in your project [![code style: @tinkoff/lin
 ```md
 [![code style: @tinkoff/linters](https://img.shields.io/badge/code%20style-%40tinkoff%2Flinters-blue)](https://github.com/TinkoffCreditSystems/linters)
 ```
-
-## Development
-
--   Intall deps with `npm run bootstrap`.
--   Run tests with `npm run test:ci`.
--   Follow [Conventional Commits specification](https://conventionalcommits.org/) for every commitmessage.
-
-## Release
-
--   Prepare your release in `master` or `release/*` branch.
--   Run `npm run version` and look what happens.
-    -   Or `npm run version -- --no-push` and `git push --follow-tags` if you not sure.
--   Run `npm run publish`.
-
-#### Pre-release:
-
-Do the same as above, except this cases:
-
--   prev version isn't prerelease, but next must be prerelease: `npm run version -- --conventional-prerelease`
--   prev version is prerelease, but next must be release: `npm run version -- --conventional-graduate`