1 | # 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 |
|
14 | [![Greenkeeper badge](https://badges.greenkeeper.io/mrseanryan/tslint-ban-snippets.svg)](https://greenkeeper.io/)
|
15 | [![Dev Dependencies](https://david-dm.org/mrseanryan/tslint-ban-snippets/dev-status.svg)](https://david-dm.org/mrseanryan/tslint-ban-snippets?type=dev)
|
16 |
|
17 | [![npm Package](https://img.shields.io/npm/v/tslint-ban-snippets.svg?style=flat-square)](https://www.npmjs.org/package/tslint-ban-snippets)
|
18 | [![NPM Downloads](https://img.shields.io/npm/dm/tslint-ban-snippets.svg)](https://npmjs.org/package/tslint-ban-snippets)
|
19 |
|
20 | [![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
|
21 | [![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)
|
22 |
|
23 | [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
|
24 | [![Donate](https://img.shields.io/badge/donate-paypal-blue.svg)](https://paypal.me/mrseanryan)
|
25 |
|
26 | ## dependencies
|
27 |
|
28 | No special dependencies - just `TypeScript` and of course `tslint`.
|
29 |
|
30 | ## custom tslint rule
|
31 |
|
32 | The custom rule `tsl-ban-snippets` can be configured with small snippets of code that should NOT be used by developers.
|
33 |
|
34 | If tslint finds the snippets of code, it will raise an error for that line of code.
|
35 |
|
36 | In this way, a code base can be kept clean of unwanted coding practices.
|
37 |
|
38 | ### note: the rule name
|
39 |
|
40 | 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.
|
41 |
|
42 | ### note: comparison to the standard `ban` rule
|
43 |
|
44 | There is 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.
|
45 |
|
46 | ## usage
|
47 |
|
48 | ### 1 Install via npm (or yarn) into your TypeScript project
|
49 |
|
50 | ```
|
51 | npm install tslint-ban-snippets
|
52 | ```
|
53 |
|
54 | ### 2 Configure tslint to pick up the custom rule
|
55 |
|
56 | Edit your `tslint.json` to have an entry `"rulesDirectory"` that points to tslint-ban-snippets.
|
57 |
|
58 | Normally this would be like:
|
59 |
|
60 | ```json
|
61 | {
|
62 | "rulesDirectory": "node_modules/tslint-ban-snippets/dist/lib",
|
63 | "rules": {
|
64 | // tslint rules here...
|
65 | }
|
66 | }
|
67 | ```
|
68 |
|
69 | ### 3 Configure the custom rule `tsl-ban-snippets`
|
70 |
|
71 | Now you can configure the custom rule, to ban whatever code snippets you do NOT want developers to use.
|
72 |
|
73 | #### examples
|
74 |
|
75 | Example of how to ban the use of "return void":
|
76 |
|
77 | ```json
|
78 | "rules": {
|
79 | // other rules here...
|
80 | "tsl-ban-snippets": [
|
81 | true,
|
82 | {
|
83 | "banned": [
|
84 | {
|
85 | "snippets": ["return void"]
|
86 | }
|
87 | ]
|
88 | }
|
89 | ]
|
90 | }
|
91 | ```
|
92 |
|
93 | Here is another example, with more options:
|
94 |
|
95 | ```json
|
96 | "rules": {
|
97 | // other rules here...
|
98 | "tsl-ban-snippets": [
|
99 | true,
|
100 | {
|
101 | "banned": [
|
102 | {
|
103 | "snippets": ["return void"],
|
104 | "message": "Please do not return void - instead place the return statement on the following line.",
|
105 | "includePaths": [".ts", ".tsx"],
|
106 | "excludePaths": ["itest"]
|
107 | }
|
108 | ]
|
109 | }
|
110 | ]
|
111 | }
|
112 | ```
|
113 |
|
114 | 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).
|
115 |
|
116 | For working examples, please see the [unit tests](https://github.com/mrseanryan/tslint-ban-snippets/blob/master/test/rules).
|
117 |
|
118 | ## sites
|
119 |
|
120 | | site | URL |
|
121 | | -------------------- | ------------------------------------------------- |
|
122 | | source code (github) | https://github.com/mrseanryan/tslint-ban-snippets |
|
123 | | github page | https://mrseanryan.github.io/tslint-ban-snippets/ |
|
124 | | npm | https://www.npmjs.com/package/tslint-ban-snippets |
|
125 |
|
126 | ## developing code in _this_ repository
|
127 |
|
128 | see the [contributing readme](CONTRIBUTING.md).
|
129 |
|
130 | ## origin
|
131 |
|
132 | This project is based on the excellent seeder project [typescript-library-starter](https://github.com/alexjoverm/typescript-library-starter).
|
133 |
|
134 | The project was started to avoid having to repeatedly fix similar coding issues in large TypeScript code bases.
|
135 |
|
136 | ### ORIGINAL readme (from the seeder project)
|
137 |
|
138 | [see here](https://github.com/mrseanryan/tslint-ban-snippets/blob/master/readme.original.md)
|
139 |
|
140 | ## authors
|
141 |
|
142 | Original work by Sean Ryan - mr.sean.ryan(at gmail.com)
|
143 |
|
144 | ## licence = MIT
|
145 |
|
146 | This project is licensed under the MIT License - see the [LICENSE](https://github.com/mrseanryan/tslint-ban-snippets/blob/master/LICENSE) file for details
|