1 | # :no_entry_sign: tslint-ban-snippets readme
|
2 |
|
3 | A custom tslint rule to ban configurable lists of code snippets.
|
4 |
|
5 | examples: "return void reject", "it.only", "debugger".
|
6 |
|
7 | ## status - stable
|
8 |
|
9 | tslint-ban-snippets is stable and in use every day in CI builds and on dev boxes (Linux, Mac, Windows) for at least one major product.
|
10 |
|
11 | [![Travis](https://img.shields.io/travis/mrseanryan/tslint-ban-snippets.svg)](https://travis-ci.org/mrseanryan/tslint-ban-snippets)
|
12 | [![Coveralls](https://img.shields.io/coveralls/mrseanryan/tslint-ban-snippets.svg)](https://coveralls.io/github/mrseanryan/tslint-ban-snippets)
|
13 | [![Size](https://packagephobia.now.sh/badge?p=tslint-ban-snippets)](https://packagephobia.now.sh/result?p=tslint-ban-snippets)
|
14 |
|
15 | [![Greenkeeper badge](https://badges.greenkeeper.io/mrseanryan/tslint-ban-snippets.svg)](https://greenkeeper.io/)
|
16 | [![Dependencies](https://david-dm.org/mrseanryan/tslint-ban-snippets.svg)](https://david-dm.org/mrseanryan/tslint-ban-snippets)
|
17 | [![Dev Dependencies](https://david-dm.org/mrseanryan/tslint-ban-snippets/dev-status.svg)](https://david-dm.org/mrseanryan/tslint-ban-snippets?type=dev)
|
18 |
|
19 | [![npm Package](https://img.shields.io/npm/v/tslint-ban-snippets.svg?style=flat-square)](https://www.npmjs.org/package/tslint-ban-snippets)
|
20 | [![NPM Downloads](https://img.shields.io/npm/dm/tslint-ban-snippets.svg)](https://npmjs.org/package/tslint-ban-snippets)
|
21 |
|
22 | [![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
|
23 | [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
|
24 |
|
25 | [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
|
26 | [![Donate](https://img.shields.io/badge/donate-paypal-blue.svg)](https://paypal.me/mrseanryan)
|
27 |
|
28 | ## dependencies
|
29 |
|
30 | No special dependencies - just `TypeScript` and of course `tslint`.
|
31 |
|
32 | ## features
|
33 |
|
34 | - a custom tslint rule that can detect code snippets that are not desired
|
35 | - configurable for multiple code snippets
|
36 | - can include/exclude file paths
|
37 | - the error message can also be configured
|
38 |
|
39 | The rule is quite flexible and could potentially avoid having to create multiple custom tslint rules.
|
40 |
|
41 | ### custom tslint rule
|
42 |
|
43 | The custom rule `tsl-ban-snippets` can be configured with small snippets of code that should NOT be used by developers.
|
44 |
|
45 | If tslint finds the snippets of code, it will raise an error for that line of code.
|
46 |
|
47 | In this way, a code base can be kept clean of unwanted coding practices.
|
48 |
|
49 | ### note: the rule name
|
50 |
|
51 | The rule name is `tsl-ban-snippets` to avoid using the prefix `tslint-` which was found to be problematic when other `tslint` libraries are in use.
|
52 |
|
53 | ### note: comparison to the standard `ban` rule
|
54 |
|
55 | There is a standard tslint rule named `ban`. However its scope is quite limited - the `tsl-ban-snippets` rule applies to any statement in a TypeScript file, and so can be configured to detect most unwanted code snippets.
|
56 |
|
57 | ## usage
|
58 |
|
59 | ### 1 Install via npm (or yarn) into your TypeScript project
|
60 |
|
61 | ```
|
62 | npm install tslint-ban-snippets
|
63 | ```
|
64 |
|
65 | ### 2 Configure tslint to pick up the custom rule
|
66 |
|
67 | Edit your `tslint.json` to have an entry `"rulesDirectory"` that points to tslint-ban-snippets.
|
68 |
|
69 | Normally this would be like:
|
70 |
|
71 | ```json
|
72 | {
|
73 | "rulesDirectory": "node_modules/tslint-ban-snippets/dist/lib",
|
74 | "rules": {
|
75 | // tslint rules here...
|
76 | }
|
77 | }
|
78 | ```
|
79 |
|
80 | ### 3 Configure the custom rule `tsl-ban-snippets`
|
81 |
|
82 | Now you can configure the custom rule, to ban whatever code snippets you do NOT want developers to use.
|
83 |
|
84 | #### examples
|
85 |
|
86 | Example of how to ban the use of "return void":
|
87 |
|
88 | ```json
|
89 | "rules": {
|
90 | // other rules here...
|
91 | "tsl-ban-snippets": [
|
92 | true,
|
93 | {
|
94 | "banned": [
|
95 | {
|
96 | "snippets": ["return void"]
|
97 | }
|
98 | ]
|
99 | }
|
100 | ]
|
101 | }
|
102 | ```
|
103 |
|
104 | Example that uses a regular expression:
|
105 |
|
106 | ```json
|
107 | "rules": {
|
108 | // other rules here...
|
109 | "tsl-ban-snippets": [
|
110 | true,
|
111 | {
|
112 | "banned": [
|
113 | {
|
114 | "regexSnippets": ["return void [reject|resolve]"],
|
115 | }
|
116 | ]
|
117 | }
|
118 | ]
|
119 | }
|
120 | ```
|
121 |
|
122 | Here is another example, with more options:
|
123 |
|
124 | ```json
|
125 | "rules": {
|
126 | // other rules here...
|
127 | "tsl-ban-snippets": [
|
128 | true,
|
129 | {
|
130 | "banned": [
|
131 | {
|
132 | "snippets": ["return void"],
|
133 | "message": "Please do not return void - instead place the return statement on the following line.",
|
134 | "includePaths": [".ts", ".tsx"],
|
135 | "excludePaths": ["itest"]
|
136 | },
|
137 | {
|
138 | "regexSnippets": ["return void [reject|resolve]"],
|
139 | "message": "Please do not return void - instead place the return statement on the following line.",
|
140 | "includePaths": [".ts", ".tsx"],
|
141 | "excludePaths": []
|
142 | }
|
143 | ]
|
144 | }
|
145 | ]
|
146 | }
|
147 | ```
|
148 |
|
149 | For more examples of how to configure, please see [tslint.json](https://github.com/mrseanryan/tslint-ban-snippets/blob/master/tslint.tslint-ban-snippets.json).
|
150 |
|
151 | For working examples, please see the [unit tests](https://github.com/mrseanryan/tslint-ban-snippets/blob/master/test/rules).
|
152 |
|
153 | ## sites
|
154 |
|
155 | | site | URL |
|
156 | | -------------------- | ------------------------------------------------- |
|
157 | | source code (github) | https://github.com/mrseanryan/tslint-ban-snippets |
|
158 | | github page | https://mrseanryan.github.io/tslint-ban-snippets/ |
|
159 | | npm | https://www.npmjs.com/package/tslint-ban-snippets |
|
160 |
|
161 | ## developing code in _this_ repository
|
162 |
|
163 | see the [contributing readme](CONTRIBUTING.md).
|
164 |
|
165 | ## origin
|
166 |
|
167 | This project is based on the excellent seeder project [typescript-library-starter](https://github.com/alexjoverm/typescript-library-starter).
|
168 |
|
169 | The project was started to avoid having to repeatedly fix similar coding issues in large TypeScript code bases.
|
170 |
|
171 | ### ORIGINAL readme (from the seeder project)
|
172 |
|
173 | [see here](https://github.com/mrseanryan/tslint-ban-snippets/blob/master/readme.original.md)
|
174 |
|
175 | ## authors
|
176 |
|
177 | Original work by Sean Ryan - mr.sean.ryan(at gmail.com)
|
178 |
|
179 | ## licence = MIT
|
180 |
|
181 | This project is licensed under the MIT License - see the [LICENSE](https://github.com/mrseanryan/tslint-ban-snippets/blob/master/LICENSE) file for details
|