https://github.com/dxheroes/dx-scanner

CLI tool that allows you to measure quality of a team work and an app based on your source code.
https://github.com/dxheroes/dx-scanner
best-practices ci cli code-review command-line-tool developer-experience developerexperience dx-recommendations dx-scanner dxscanner java javascript practices ruby typescript
Last synced: 10 days ago
JSON representation
CLI tool that allows you to measure quality of a team work and an app based on your source code.
Host: GitHub
URL: https://github.com/dxheroes/dx-scanner
Owner: DXHeroes
License: mit
Created: 2019-07-31T06:50:27.000Z (over 5 years ago)
Default Branch: master
Last Pushed: 2025-03-28T18:48:30.000Z (25 days ago)
Last Synced: 2025-04-02T08:39:39.796Z (20 days ago)
Topics: best-practices, ci, cli, code-review, command-line-tool, developer-experience, developerexperience, dx-recommendations, dx-scanner, dxscanner, java, javascript, practices, ruby, typescript
Language: TypeScript
Homepage: https://dxscanner.io
Size: 8.4 MB
Stars: 82
Watchers: 3
Forks: 45
Open Issues: 36
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project

README

        [![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)



  



[![Slack](https://img.shields.io/badge/slack-@DeveloperExperience-%234A154B.svg?logo=slack)](https://bit.ly/slack_developer_experience)

[![Pipeliner Roadmap](https://img.shields.io/badge/public%20roadmap-https%3A%2F%2Froadmap.dxheroes.io-%23108DE4)](https://roadmap.dxheroes.io)

[![Version](https://img.shields.io/npm/v/dx-scanner.svg)](https://npmjs.org/package/dx-scanner)

[![Travis (.org)](https://img.shields.io/travis/DXHeroes/dx-scanner/master)](https://travis-ci.org/DXHeroes/dx-scanner)

[![codecov](https://codecov.io/gh/DXHeroes/dx-scanner/branch/master/graph/badge.svg)](https://codecov.io/gh/DXHeroes/dx-scanner)

![last commit](https://img.shields.io/github/last-commit/DXHeroes/dx-scanner)

![GitHub commit activity](https://img.shields.io/github/commit-activity/w/DXHeroes/dx-scanner)

[![Downloads/week](https://img.shields.io/npm/dw/dx-scanner.svg)](https://npmjs.org/package/dx-scanner)

![GitHub contributors](https://img.shields.io/github/contributors/DXHeroes/dx-scanner)

[![All Contributors](https://img.shields.io/badge/all_contributors-5-orange.svg)](#contributors-)

[![NPM](https://img.shields.io/npm/l/dx-scanner)](LICENSE)

![TypeScript](https://img.shields.io/badge/%3C%2F%3E-Typescript-blue)

---

## What is DX Scanner?

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.

### What language is supported?

Language | Supported

------------ | -------------

JavaScript/TypeScript | ✅

Java/Kotlin | ✅

Python | ✅

Go | ✅

PHP | ✅

Ruby | ✅

Rust | ✅

C++ | 🚧

C# | 🚧

Android | 🚧

Swift | 🚧

## Table of Contents

* [Supported version control systems](#Which-version-control-system-can-you-use)

* [Getting Started](#Getting-Started-)

  * [Installation](#Installation)

  * [Usage](#Usage)

    * [Commands](#Commands)

    * [Options for dx-scanner run](#options-for-dx-scanner-run)

    * [Auto-fixer](#Auto-fixer)

* [Supported Languages](#What-language-is-supported)

* [Configuration](#configuration-%EF%B8%8F)

  * [Practices](#Practices)

  * [CI Mode](#CI-mode)

  * [GitHub CI Action](#GitHub-Ci-Action)

* [Support](#support-%EF%B8%8F-%EF%B8%8F)

* [Contributing](#Contributing--)

  * [Roadmap](#Roadmap)

### Which version control system can you use?

Sure you can use `GitHub`. You can also use `GitLab` and `Bitbucket` no matter if it is public or private repo!

examples:

```

dx-scanner run https://github.com/DXHeroes/dx-scanner

dx-scanner run https://gitlab.com/ubon-refer/smart-refer-api

dx-scanner run https://bitbucket.org/maras333/node-api-with-ts

```

## Getting Started 🏁

### Dependencies

- npm ([how to install npm](https://www.npmjs.com/get-npm))

- git ([how to install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git))

- (optional) yarn ([how to install npm](https://www.npmjs.com/get-npm) and [yarn](https://yarnpkg.com/getting-started/install))

### Installation

- with NPM

  ```npm install -g dx-scanner```

- with Yarn

  ```yarn global add dx-scanner```

### Usage

```

  dx-scanner run [path] [options]

```

Example:

```

  dx-scanner run https://github.com/DXHeroes/dx-scanner

```

#### Commands

```

Usage: dx-scanner [command] [options]

Options:

  -V, --version         output the version number

  -l --log              Write a debug and dxs output log to ./dxscanner.log

  -h, --help            display help for command

Commands:

  run [options] [path]  Scan your project for possible DX recommendations

  init                  Initialize DX Scanner configuration

  practices [options]   List all practices id with name and impact

  help [command]        display help for command

Aliases:

  dxs

  dxscanner

```

#### Options for `dx-scanner run`

```

Usage: dx-scanner run [path] [options]

Scan your project for possible DX recommendations

Options:

  -a --authorization   credentials to the repository (in format "token" or "username:token"; can be set as ENV variable DXSCANNER_GIT_SERVICE_TOKEN)

  -t --apiToken             credentials to DX Scanner, can be set as ENV variable DXSCANNER_API_TOKEN

  --apiUrl                    URL of DX Scanner API, can be set as ENV variable DXSCANNER_API_URL (default: https://provider.dxscanner.io/api/v1)

  --ci                                CI mode (default: false)

  -d --details                        print details in reports

  --fail                      exits process with code 1 for any non-practicing condition of given level (high|medium|small|hint|off|all) (default: "off")

  --fix                               tries to fix problems automatically (default: false)

  --fixPattern               fix only rules with IDs matching the regex

  -j --json                           print report in JSON (default: false)

  --html [path]                       save report in HTML file (default: false, default path: ./report.html)

  -r --recursive                      scan all components recursively in all sub folders (default: false)

  --no-recursive                      disable recursive scan in CI mode

  -h, --help                          output usage information

Examples:

  dx-scanner run

  dx-scanner run ./ --fail=high

  dx-scanner run github.com/DXHeroes/dx-scanner

```

#### Auto-fixer

Fix problems detected by DX Scanner automatically.

```

dx-scanner run [PATH] --fix

```

This will try to fix all *fixable* practices which are not being practices yet.

If you want to omit a practice from automatic fixing, you can do it in the configuration file (see below).

You can also specify `fixPattern` flag to fix only a subset of *fixable* practices.

```

dx-scanner run [PATH] --fix --fixPattern=lint

```

Please note, that `fixPattern` flag overrides `fix` settings from configuration file. Therefore practices omitted from fixing by configuration file, but included through `fixPattern` will be fixed.

## Configuration ⚙️

Add ```dxscannerrc.*``` config file to change default configuration settings. It can be a ```.json```, ```.yml```, or even a dotfile!

You can also run ```dx-scanner init``` to initialize config automatically.

### Practices

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.

List of All Practices 🔍

Practice | Impact | Language Independent | JavaScript/TypeScript | Java/Kotlin | Python | PHP

------------- | ------------- | ------------- | ------------- | ------------- | ------------- | -------------

Create a Readme File | high | ✅ | ✅ | ✅ | ✅ | ✅

Create a Changelog File | high | ✅ | ✅ | ✅ | ✅ | ✅

Create a License File | medium | ✅ | ✅ | ✅ | ✅ | ✅

Create a Lockfile | high | ✅ | ✅ | ✅ | ✅ | ✅

Create a .gitignore | high | ✅ | ✅ | ✅ | ✅ | ✅

Write in Typescript | medium | ❌ | ✅ | ❌ | ❌ | ❌

Set .gitignore Correctly | high | ❌ | ✅ | ✅ | ❌ | ❌

Set Readme File Correctly | high | ✅ | ✅ | ✅ | ✅ | ✅

Use Continuous Integration | high | ✅ | ✅ | ✅ | ✅ | ✅

Use Docker | small | ✅ | ✅ | ✅ | ✅ | ✅

Use .editorconfig | small | ✅ | ✅ | ✅ | ✅ | ✅

Format your code automatically | small | ❌ | ✅ | ❌ | ❌ | ❌

Use a Linter | medium | ❌ | ✅ | ✅ | ✅ | ✅

ESLint Without Errors | medium | ❌ | ✅ | ❌ | ❌ | ❌

Use a different linter | medium | ❌ | ✅ | ❌ | ❌ | ❌

Use JS Frontend Testing Framework | medium | ❌ | ✅ | ❌ | ❌ | ❌

Use JS Frontend Build Tools | medium | ❌ | ✅ | ❌ | ❌ | ❌

Use JS Backend Testing Frameworks | high | ❌ | ✅ | ❌ | ❌ | ❌

Use a JS Logging Library | small | ❌ | ✅ | ❌ | ❌ | ❌

Use Package Management | high | ❌ | ✅ | ✅ | ❌ | ❌

Configure Scripts in package.json | medium | ❌ | ✅ | ❌ | ❌ | ❌

Update Dependencies of Major Level | small | ❌ | ✅ | ✅ | ❌ | ❌

Update Dependencies of Minor and Patch Level | high | ❌ | ✅ | ✅ | ❌  | ❌

Do PullRequests | medium | ✅ | ✅ | ✅ | ✅ | ✅

Break down large pull requests into smaller ones | medium | ✅ | ✅ | ✅ | ✅ | ✅

Solve Pull Requests Continuously | medium | ✅ | ✅ | ✅ | ✅ | ✅

Solve Issues Continuously | medium | ✅ | ✅ | ✅ | ✅ | ✅

Write Commit Messages by Convention | small | ✅ | ✅ | ✅ | ✅ | ✅

Use Mocking Frameworks for Tests  | small | ❌ | ✅ | ✅ | ❌ | ❌

Use Testing Frameworks | high | ❌ | ❌ | ✅ | ❌ | ❌

Use a Java Logging Dependency | small | ❌ | ❌ | ✅ | ❌ | ❌

Use Java Class Naming Convention | small | ❌ | ❌ | ✅ | ❌ | ❌

Specify Versions of Dependencies | high | ❌ | ❌ | ✅ | ❌ | ❌

Store Environment Variables Using .properties Files | medium | ❌ | ❌ | ✅ | ❌ | ❌

Use Java Code Styles | small | ❌ | ❌ | ✅ | ❌ | ❌

Use Java Logger Configuration Files | small | ❌ | ❌ | ✅ | ❌ | ❌

Security vulnerabilities detected | high | ❌ | ✅ | ❌ | ❌ | ❌

Possible impact:

```

high

medium

small

hint

off

```

Example `dxscannerrc.json`:

```json

{

    "practices": {

        "JavaScript.GitignoreCorrectlySet": "medium",

        "JavaScript.LoggerUsed": "off",

        "LanguageIndependent.DoesPullRequests": {

          "impact": "small"

        },

        "JavaScript.ESLintWithoutErrorsPractice": {

          "fix": true,

          "override": {

            "lintFilesPatterns": [".internal/**/*.js", "*.js"],

            "ignorePatterns": []

          }

        },

        "LanguageIndependent.ThinPullRequestsPractice": {

          "impact": "high",

          "override": {

            "measurePullRequestCount": 500

          }

        }

    }

}

```

In order to override the default values of certain practices, specify `override` and nest the correct overridable variables.

Example `dxscannerrc.yaml`:

```yaml

---

practices:

  JavaScript.GitignoreCorrectlySet: medium

  JavaScript.LoggerUsed: 'off'

  LanguageIndependent.DoesPullRequests:

    impact: small

  JavaScript.ESLintWithoutErrorsPractice:

    fix: true

    override:

      lintFilesPatterns: ['.internal/**/*.js', '*.js']

      ignorePatterns: []

  LanguageIndependent.ThinPullRequestsPractice:

    impact: high

    override:

      measurePullRequestCount: 500

```

### CI Mode

When running DX Scanner with `--ci` flag, it runs in CI Mode. In CI Mode, DX SCanner uses `CIReporter` for its output and runs recursively by default (i.e. the `--recursive` flag is turned on).

If you want to disable recursive scan in CI mode, use the `--no-recursive` flag.

### Github CI Action

**Basic example**: run DX Scanner on each push to the repo

Create `.github/workflows/main.yml`.

```yml

name: DX Scanner

on: push

jobs:

  dx-scanner:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v1

      - name: Runs DX Scanner on the code

        uses: DXHeroes/dx-scanner@master

        with:

          github_token: ${{ secrets.GITHUB_TOKEN }}

```

[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`.

## Score Computation 💯

The impact of each practice is represented by a specific value. DX Scanner uses these values to calculate the overall DX Score.

```

high = 100 points

medium = 75 points

small = 50 points

hint = 25 points

```

The practices you have switched off are not included in the calculation (0 points).

## Support 🦸‍♀️ 🦸‍♂️

Didn't you find what you expected? Contact us via our public [Slack!](https://bit.ly/slack_developer_experience)

## Contributing 👩‍💻 👨‍💻

Feel free to contribute to our DX Scanner. Please follow the [Contribution Guide](CONTRIBUTING.md).

### Roadmap 

See our [public roadmap](https://roadmap.dxheroes.io).

## License 📝

The DX Scanner open source project is licensed under the [MIT](LICENSE).

## Contributors ✨

Many thanks to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

  

    
_{Prokop Simek}
💻 🚧

    
_adelkah
💻 🚧

    
_{Radek Holý}
💻

    
_{Vratislav Kalenda}
💻 🤔

    
_{Petr Vnenk}
💻

    
_{Cuong Nguyen}
💻

    
_vlasy
💻

  

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Any kind of contributions are welcome!
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/dxheroes/dx-scanner

Awesome Lists containing this project

README
