1 | [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=DX%20Scanner%20is%20an%20open%20source%20CLI%20tool%20that%20allows%20you%20to%20“measure”%20Developer%20Experience%20directly%20based%20on%20your%20source%20code.&url=https://github.com/DXHeroes/dx-scanner&via=dx_heroes&hashtags=developer-experience,dxheroes,developers)
|
2 |
|
3 | <p align="center">
|
4 | <a href="https://dxscanner.io" target="_blank"><img src="https://github.com/DXHeroes/dx-scanner/blob/master/docs/logo.svg" /></a>
|
5 | </p>
|
6 |
|
7 | [![Slack](https://img.shields.io/badge/slack-@DeveloperExperience-%234A154B.svg?logo=slack)](https://bit.ly/slack_developer_experience)
|
8 |
|
9 | [![Version](https://img.shields.io/npm/v/dx-scanner.svg)](https://npmjs.org/package/dx-scanner)
|
10 | [![Travis (.org)](https://img.shields.io/travis/DXHeroes/dx-scanner/master)](https://travis-ci.org/DXHeroes/dx-scanner)
|
11 | [![codecov](https://codecov.io/gh/DXHeroes/dx-scanner/branch/master/graph/badge.svg)](https://codecov.io/gh/DXHeroes/dx-scanner)
|
12 | ![last commit](https://img.shields.io/github/last-commit/DXHeroes/dx-scanner)
|
13 | ![GitHub commit activity](https://img.shields.io/github/commit-activity/w/DXHeroes/dx-scanner)
|
14 | [![Downloads/week](https://img.shields.io/npm/dw/dx-scanner.svg)](https://npmjs.org/package/dx-scanner)
|
15 | ![GitHub contributors](https://img.shields.io/github/contributors/DXHeroes/dx-scanner)
|
16 | [![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg)](#contributors-)
|
17 | [![NPM](https://img.shields.io/npm/l/dx-scanner)](LICENSE)
|
18 | ![TypeScript](https://img.shields.io/badge/%3C%2F%3E-Typescript-blue)
|
19 |
|
20 | ---
|
21 |
|
22 | ## What is DX Scanner?
|
23 |
|
24 | DX Scanner is an open source CLI tool that allows you to “measure” Developer Experience directly based on your source code. DX Scanner recommends practices that can help you with improving your product development. You can fix some problems automatically with just one command.
|
25 |
|
26 | ### What language is supported?
|
27 |
|
28 | Language | Supported
|
29 | ------------ | -------------
|
30 | JavaScript/TypeScript | ✅
|
31 | Java/Kotlin | ✅
|
32 | Python | ✅
|
33 | PHP | 🚧
|
34 | C++ | 🚧
|
35 | C# | 🚧
|
36 | Ruby | 🚧
|
37 |
|
38 | ## Table of Contents
|
39 |
|
40 |
|
41 | * [Supported version control systems](#Which-version-control-system-can-you-use)
|
42 | * [Getting Started](#Getting-Started-)
|
43 | * [Installation](#Installation)
|
44 | * [Usage](#Usage)
|
45 | * [Commands](#Commands)
|
46 | * [Options for dx-scanner run](#options-for-dx-scanner-run)
|
47 | * [Auto-fixer](#Auto-fixer)
|
48 | * [Supported Languages](#What-language-is-supported)
|
49 | * [Configuration](#configuration-%EF%B8%8F)
|
50 | * [Practices](#Practices)
|
51 | * [GitHub CI Action](#GitHub-Ci-Action)
|
52 | * [Support](#support-%EF%B8%8F-%EF%B8%8F)
|
53 | * [Contributing](#Contributing--)
|
54 |
|
55 | ### Which version control system can you use?
|
56 |
|
57 | Sure you can use `GitHub`. You can also use `GitLab` and `Bitbucket` no matter if it is public or private repo!
|
58 |
|
59 | examples:
|
60 | ```
|
61 | dx-scanner run https://github.com/DXHeroes/dx-scanner
|
62 |
|
63 | dx-scanner run https://gitlab.com/ubon-refer/smart-refer-api
|
64 |
|
65 | dx-scanner run https://bitbucket.org/maras333/node-api-with-ts
|
66 | ```
|
67 |
|
68 | ## Getting Started 🏁
|
69 |
|
70 | ### Installation
|
71 |
|
72 | - with NPM
|
73 |
|
74 | ```npm install -g dx-scanner```
|
75 | - with Yarn
|
76 |
|
77 | ```yarn global add dx-scanner```
|
78 |
|
79 | ### Usage
|
80 | <!--
|
81 | Quick start
|
82 | -->
|
83 | ```
|
84 | dx-scanner run [path] [options]
|
85 | ```
|
86 |
|
87 | Example:
|
88 | ```
|
89 | dx-scanner run https://github.com/DXHeroes/dx-scanner
|
90 | ```
|
91 |
|
92 | <!--
|
93 | Help for command dxs
|
94 | -->
|
95 | #### Commands
|
96 | ```
|
97 | Usage: dx-scanner [command] [options]
|
98 |
|
99 | Options:
|
100 | -V, --version output the version number
|
101 | -h, --help display help for command
|
102 |
|
103 | Commands:
|
104 | run [options] [path] Scan your project for possible DX recommendations
|
105 | init Initialize DX Scanner configuration
|
106 | practices [options] List all practices id with name and impact
|
107 | help [command] display help for command
|
108 |
|
109 | Aliases:
|
110 | dxs
|
111 | dxscanner
|
112 | ```
|
113 |
|
114 | #### Options for `dx-scanner run`
|
115 |
|
116 | ```
|
117 | Usage: dx-scanner run [path] [options]
|
118 |
|
119 | Scan your project for possible DX recommendations
|
120 |
|
121 | Options:
|
122 | -a --authorization <authorization> credentials to the repository (in format "token" or "username:token"; can be set as ENV variable DXSCANNER_GIT_SERVICE_TOKEN)
|
123 | --ci CI mode (default: false)
|
124 | -d --details print details in reports
|
125 | --fail <impact> exits process with code 1 for any non-practicing condition of given level (high|medium|small|hint|off|all) (default: "high")
|
126 | --fix tries to fix problems automatically (default: false)
|
127 | --fixPattern <pattern> fix only rules with IDs matching the regex
|
128 | -j --json print report in JSON (default: false)
|
129 | --html [path] save report in HTML file (default: false, default path: ./report.html)
|
130 | -r --recursive scan all components recursively in all sub folders (default: false)
|
131 | -h, --help output usage information
|
132 |
|
133 | Examples:
|
134 | dx-scanner run
|
135 | dx-scanner run ./ --fail=high
|
136 | dx-scanner run github.com/DXHeroes/dx-scanner
|
137 | ```
|
138 | </details>
|
139 |
|
140 | #### Auto-fixer
|
141 |
|
142 | Fix problems detected by DX Scanner automatically.
|
143 | ```
|
144 | dx-scanner run [PATH] --fix
|
145 | ```
|
146 |
|
147 | This will try to fix all *fixable* practices which are not being practices yet.
|
148 | If you want to omit a practice from automatic fixing, you can do it in the configuration file (see below).
|
149 |
|
150 | You can also specify `fixPattern` flag to fix only a subset of *fixable* practices.
|
151 | ```
|
152 | dx-scanner run [PATH] --fix --fixPattern=lint
|
153 | ```
|
154 |
|
155 | Please note, that `fixPattern` flag overrides `fix` settings from configuration file. Therefore practices ommited from fixing by configuration file, but included through `fixPattern` will be fixed.
|
156 |
|
157 | ## Configuration ⚙️
|
158 | Add ```dxscannerrc.*``` config file to change default configuration settings. It can be a ```.json```, ```.yml```, or even a dotfile!
|
159 |
|
160 | You can also run ```dx-scanner init``` to initialize config automatically.
|
161 |
|
162 | ### Practices
|
163 | You can switch off practices that you do not want to scan, change their impact level, and even override their default values. To do so, refer to the id of the practice and specify your configuration.
|
164 |
|
165 | <details>
|
166 | <summary>List of All Practices 🔍</summary>
|
167 |
|
168 | Practice | Impact | Language Independent | JavaScript/TypeScript | Java/Kotlin | Python
|
169 | ------------- | ------------- | ------------- | ------------- | ------------- | -------------
|
170 | Create a Readme File | <span style="color:red">high</span> | ✅ | ✅ | ✅ | ✅
|
171 | Create a License File | <span style="color:yellow">medium</span> | ✅ | ✅ | ✅ | ✅
|
172 | Create a Lockfile | <span style="color:red">high</span> | ✅ | ✅ | ✅ | ✅
|
173 | Create a .gitignore | <span style="color:red">high</span> | ✅ | ✅ | ✅ | ✅
|
174 | Write in Typescript | <span style="color:yellow">medium</span> | ❌ | ✅ | ❌ | ❌
|
175 | Set .gitignore Correctly | <span style="color:red">high</span> | ❌ | ✅ | ✅ | ❌
|
176 | Use Continuous Integration | <span style="color:red">high</span> | ✅ | ✅ | ✅ | ✅
|
177 | Use Docker | <span style="color:green">small</span> | ✅ | ✅ | ✅ | ✅
|
178 | Use .editorconfig | <span style="color:green">small</span> | ✅ | ✅ | ✅ | ✅
|
179 | Format your code automatically | <span style="color:green">small</span> | ❌ | ✅ | ❌ | ❌
|
180 | Use ESLint | <span style="color:yellow">medium</span> | ❌ | ✅ | ❌ | ❌
|
181 | ESLint Without Errors | <span style="color:yellow">medium</span> | ❌ | ✅ | ❌ | ❌
|
182 | Use a different linter | <span style="color:yellow">medium</span> | ❌ | ✅ | ❌ | ❌
|
183 | Use JS Frontend Testing Framework | <span style="color:yellow">medium</span> | ❌ | ✅ | ❌ | ❌
|
184 | Use JS Frontend Build Tools | <span style="color:yellow">medium</span> | ❌ | ✅ | ❌ | ❌
|
185 | Use JS Backend Testing Frameworks | <span style="color:red">high</span> | ❌ | ✅ | ❌ | ❌
|
186 | Use a JS Logging Library | <span style="color:green">small</span> | ❌ | ✅ | ❌ | ❌
|
187 | Use Package Management | <span style="color:red">high</span> | ❌ | ✅ | ✅ | ❌
|
188 | Configure Scripts in package.json | <span style="color:yellow">medium</span> | ❌ | ✅ | ❌ | ❌
|
189 | Update Dependencies of Major Level | <span style="color:green">small</span> | ❌ | ✅ | ✅ | ❌
|
190 | Update Dependencies of Minor and Patch Level | <span style="color:red">high</span> | ❌ | ✅ | ✅ | ❌
|
191 | Do PullRequests | <span style="color:yellow">medium</span> | ✅ | ✅ | ✅ | ✅
|
192 | Break down large pull requests into smaller ones | <span style="color:yellow">medium</span> | ✅ | ✅ | ✅ | ✅
|
193 | Solve Pull Requests Continuously | <span style="color:yellow">medium</span> | ✅ | ✅ | ✅ | ✅
|
194 | Solve Issues Continuously | <span style="color:yellow">medium</span> | ✅ | ✅ | ✅ | ✅
|
195 | Write Commit Messages by Convention | <span style="color:green">small</span> | ✅ | ✅ | ✅ | ✅
|
196 | Use Mocking Frameworks for Tests | <span style="color:green">small</span> | ❌ | ✅ | ✅ | ❌
|
197 | Use Testing Frameworks | <span style="color:red">high</span> | ❌ | ❌ | ✅ | ❌
|
198 | Use a Java Logging Dependency | <span style="color:green">small</span> | ❌ | ❌ | ✅ | ❌
|
199 | Use a Java Linter Dependency | <span style="color:green">small</span> | ❌ | ❌ | ✅ | ❌
|
200 | Use Java Class Naming Convention | <span style="color:green">small</span> | ❌ | ❌ | ✅ | ❌
|
201 | Specify Versions of Dependencies | <span style="color:red">high</span> | ❌ | ❌ | ✅ | ❌
|
202 | Store Environment Variables Using .properties Files | <span style="color:yellow">medium</span> | ❌ | ❌ | ✅ | ❌
|
203 | Use Java Code Styles | <span style="color:green">small</span> | ❌ | ❌ | ✅ | ❌
|
204 | Use Java Logger Configuration Files | <span style="color:green">small</span> | ❌ | ❌ | ✅ | ❌
|
205 | Security vulnerabilities detected | <span style="color:red">high</span> | ❌ | ✅ | ❌ | ❌
|
206 | </details>
|
207 |
|
208 | Possible impact:
|
209 | ```
|
210 | high
|
211 |
|
212 | medium
|
213 |
|
214 | small
|
215 |
|
216 | hint
|
217 |
|
218 | off
|
219 | ```
|
220 |
|
221 | Example `dxscannerrc.json`:
|
222 |
|
223 | ```json
|
224 | {
|
225 | "practices": {
|
226 | "JavaScript.GitignoreCorrectlySet": "medium",
|
227 | "JavaScript.LoggerUsed": "off",
|
228 | "LanguageIndependent.DoesPullRequests": {
|
229 | "impact": "small"
|
230 | },
|
231 | "JavaScript.ESLintWithoutErrorsPractice": {
|
232 | "fix": true
|
233 | },
|
234 | "LanguageIndependent.ThinPullRequestsPractice": {
|
235 | "impact": "high",
|
236 | "override": {
|
237 | "measurePullRequestCount": 500
|
238 | }
|
239 | }
|
240 | }
|
241 | }
|
242 | ```
|
243 |
|
244 | In order to override the default values of certain practices, specify `override` and nest the correct overridable variables.
|
245 |
|
246 | Example `dxscannerrc.yaml`:
|
247 |
|
248 | ```yaml
|
249 | ---
|
250 | practices:
|
251 | JavaScript.GitignoreCorrectlySet: medium
|
252 | JavaScript.LoggerUsed: 'off'
|
253 | LanguageIndependent.DoesPullRequests:
|
254 | impact: small
|
255 | JavaScript.ESLintWithoutErrorsPractice:
|
256 | fix: true
|
257 | LanguageIndependent.ThinPullRequestsPractice:
|
258 | impact: high
|
259 | override:
|
260 | measurePullRequestCount: 500
|
261 | ```
|
262 |
|
263 | ### Github CI Action
|
264 |
|
265 | **Basic example**: run DX Scanner on each push to the repo
|
266 |
|
267 | Create `.github/workflows/main.yml`.
|
268 |
|
269 | ```yml
|
270 | name: DX Scanner
|
271 | on: push
|
272 | jobs:
|
273 | dx-scanner:
|
274 | runs-on: ubuntu-latest
|
275 | steps:
|
276 | - uses: actions/checkout@v1
|
277 | - name: Runs DX Scanner on the code
|
278 | uses: DXHeroes/dx-scanner@master
|
279 | with:
|
280 | github_token: ${{ secrets.GITHUB_TOKEN }}
|
281 | ```
|
282 |
|
283 | [Generate your Github personal token](https://github.com/settings/tokens/new) and [set it as an encrypted secret](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets) named `GITHUB_TOKEN`.
|
284 |
|
285 | ## Score Computation 💯
|
286 | The impact of each practice is represented by a specific value. DX Scanner uses these values to calculate the overall DX Score.
|
287 |
|
288 | ```
|
289 | high = 100 points
|
290 |
|
291 | medium = 75 points
|
292 |
|
293 | small = 50 points
|
294 |
|
295 | hint = 25 points
|
296 | ```
|
297 |
|
298 | The practices you have switched off are not included in the calculation (0 points).
|
299 |
|
300 | ## Support 🦸♀️ 🦸♂️
|
301 | Didn't you find what you expected? Contact us via our public [Slack!](https://bit.ly/slack_developer_experience)
|
302 |
|
303 | ## Contributing 👩💻 👨💻
|
304 | Feel free to contribute to our DX Scanner. Please follow the [Contribution Guide](CONTRIBUTING.md).
|
305 |
|
306 | ## License 📝
|
307 |
|
308 | The DX Scanner open source project is licensed under the [MIT](LICENSE).
|
309 |
|
310 | ## Contributors ✨
|
311 |
|
312 | Many thanks to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
|
313 |
|
314 |
|
315 |
|
316 |
|
317 | <table>
|
318 | <tr>
|
319 | <td align="center"><a href="https://github.com/prokopsimek"><img src="https://avatars2.githubusercontent.com/u/5487217?v=4" width="100px;" alt=""/><br /><sub><b>Prokop Simek</b></sub></a><br /><a href="https://github.com/DXHeroes/dx-scanner/commits?author=prokopsimek" title="Code">💻</a> <a href="#maintenance-prokopsimek" title="Maintenance">🚧</a></td>
|
320 | <td align="center"><a href="https://github.com/adelkahomolova"><img src="https://avatars2.githubusercontent.com/u/53510747?v=4" width="100px;" alt=""/><br /><sub><b>adelkah</b></sub></a><br /><a href="https://github.com/DXHeroes/dx-scanner/commits?author=adelkahomolova" title="Code">💻</a> <a href="#maintenance-adelkahomolova" title="Maintenance">🚧</a></td>
|
321 | <td align="center"><a href="https://github.com/radektheloner"><img src="https://avatars3.githubusercontent.com/u/7268060?v=4" width="100px;" alt=""/><br /><sub><b>Radek Holý</b></sub></a><br /><a href="https://github.com/DXHeroes/dx-scanner/commits?author=radektheloner" title="Code">💻</a></td>
|
322 | <td align="center"><a href="http://www.applifting.cz"><img src="https://avatars2.githubusercontent.com/u/346066?v=4" width="100px;" alt=""/><br /><sub><b>Vratislav Kalenda</b></sub></a><br /><a href="https://github.com/DXHeroes/dx-scanner/commits?author=Vratislav" title="Code">💻</a> <a href="#ideas-Vratislav" title="Ideas, Planning, & Feedback">🤔</a></td>
|
323 | <td align="center"><a href="http://www.petrvnenk.com"><img src="https://avatars2.githubusercontent.com/u/1933654?v=4" width="100px;" alt=""/><br /><sub><b>Petr Vnenk</b></sub></a><br /><a href="https://github.com/DXHeroes/dx-scanner/commits?author=vnenkpet" title="Code">💻</a></td>
|
324 | <td align="center"><a href="https://github.com/ryzzaki"><img src="https://avatars1.githubusercontent.com/u/31356058?v=4" width="100px;" alt=""/><br /><sub><b>Cuong Nguyen</b></sub></a><br /><a href="https://github.com/DXHeroes/dx-scanner/commits?author=ryzzaki" title="Code">💻</a></td>
|
325 | <td align="center"><a href="https://github.com/vlasy"><img src="https://avatars3.githubusercontent.com/u/13099178?v=4" width="100px;" alt=""/><br /><sub><b>vlasy</b></sub></a><br /><a href="https://github.com/DXHeroes/dx-scanner/commits?author=vlasy" title="Code">💻</a></td>
|
326 | </tr>
|
327 | </table>
|
328 |
|
329 |
|
330 |
|
331 |
|
332 |
|
333 | This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Any kind of contributions are welcome!
|