https://github.com/wallet77/qualscan
A CLI, and API, tool to run many quality check-ups on your javascript project.
https://github.com/wallet77/qualscan
budget dependencies-tree javascript jscpd npm package quality thresholds
Last synced: 3 months ago
JSON representation
A CLI, and API, tool to run many quality check-ups on your javascript project.
- Host: GitHub
- URL: https://github.com/wallet77/qualscan
- Owner: wallet77
- License: mit
- Created: 2020-11-16T21:59:28.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-09-04T13:40:12.000Z (6 months ago)
- Last Synced: 2024-10-05T03:28:43.267Z (5 months ago)
- Topics: budget, dependencies-tree, javascript, jscpd, npm, package, quality, thresholds
- Language: JavaScript
- Homepage:
- Size: 2.16 MB
- Stars: 26
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-github-star - qualscan - ups on your javascript project. | wallet77 | 23 | (JavaScript)
README
[](https://github.com/wallet77/qualscan/releases/)
[](https://github.com/wallet77/qualscan/blob/master/LICENSE)
[](https://github.com/wallet77/qualscan/pulls)
[](https://github.com/wallet77/qualscan/issues)
[](https://deepscan.io/dashboard#view=project&tid=12061&pid=15017&bid=292479)
[](https://github.com/wallet77/qualscan/actions?query=workflow%3A%22Node.js+CI%22)
[](https://codecov.io/gh/wallet77/qualscan)
[](https://github.com/wallet77/qualscan)
# Qualscan = Quality Scanner
**Qualscan analizes any type of project built on Javascript (NPM module, backend app, frontend app, etc).**
Purpose •
Installation •
Usage •
Using config file •
Reporters •
API •
Budget •
CI / CD •
Test •
License
## Purpose
A CLI tool to run multiple plugins in order to check the quality of your Javascript project.
**List of features:**
- security audit of your dependencies
- check dependencies updates
- check code duplications
- check project's size (bundle's size, number of files)
- check project's structure (readme, license, etc)
- check exact version of dependencies
- check dependencies (missing or unused)
- check dependencies size (number of dep, actual size, tree's depth)
- require time of entrypoint (loading time when we require your project)
In addition you can run all you custom scripts.
It will give you a global score based on the number of successful tasks.
## Output
This tool will basically returns 1 if, at least, one task has failed, otherwise it returns 0.
Basic error output:
A task is considered as successful if the `fail` threhsold (see budgets) has not been exceeded.
`warn` of `info` thresholds will bring you more information but the task will be considered as successful even if the thresholds are exceeded.
## Installation
```bash
$ npm install qualscan -g
```
## Usage
```bash
$ qualscan
```
### Options
**Display all existing options**
```bash
$ qualscan -h
```
**Run only a set of tasks**
```bash
$ qualscan --tasks security-audit updates
```
**Run only a set of scripts**
```bash
$ qualscan --scripts test
```
**Display tasks messages**
```bash
$ qualscan -v
```
**Display tasks messages by level**
```bash
$ qualscan -v -l warn
```
| Level | Description |
|:-------------:|:--------------------------------:|
| all | (default) display all logs |
| error | Display errors only |
| warn | Display warnings & errors |
| info | Display info & errors & warnings |
**Send custom args to jscpd**
```bash
$ qualscan -cda "--ignore tests/resources/code_duplication_failed/*"
```
For a full list of possible arguments, please follow this documentation: [Jscpd doc](https://github.com/kucherenko/jscpd/tree/master/packages/jscpd).
**Check exact version for dev dependencies**
```bash
$ qualscan -devd
```
**Export current configuration**
```bash
$ qualscan exportConf
```
## Using Config file
Qualscan can use a configuration file instead of a list of options.
You can specify your configuration file in two different ways:
1. **Use .qualscanrc file**
By default, Qualscan will check if .qualscanrc file is present in the current directory.
You can find an [example here](https://github.com/wallet77/qualscan/tree/main/examples/.qualscanrc).
```json
{
"scripts": ["linter"],
"tasks": [
"code-duplication",
"security-audit",
"updates",
"package-check",
"dependencies-exact-version",
"project-size",
"dependencies-check",
"dependencies-size",
"require-time"
],
"code-duplication": {
"args": "--ignore */resources/code_duplication_failed/* --gitignore"
},
"verbose": true,
"level": "error"
}
```
2. **Use the option -c**
```bash
$ qualscan -c /pathTo/MyConfigFile.json
```
## Reporters
By default qualscan will use `text` reporter and display results in the console.
Allowed reporters:
- text
- json
- json in console
```bash
qualscan --reporters json
```
By default the default path to store the report is: [workingDir]/report/qualscan_report.json
Define another report directory
```bash
qualscan --reporters json --reportPath "myCustomDir/"
```
To display json in console
```bash
qualscan --reporters json --reportPath ""
```
## API
```javascript
const qualscan = require('qualscan')
const report = await qualscan.run({
tasks: ['code-duplication', 'project-size'],
scripts: ['linter'],
reporters: ['json'],
reportPath: '' // return the report as JSON object
}, 'path/to/my/project')
```
## Budget
The notion of budget comes from the [Webperf budget principle](https://developer.mozilla.org/en-US/docs/Web/Performance/Performance_budgets).
With this powerful tool you can define your own thresholds for each plugin.
The principle is the following:
* for each plugin, define your thresholds: fail, warn or info
* for each threshold set a value for every metrics
Example in config file (for project's size plugin):
```bash
{
"project-size": {
"budget": {
"fail": {
"entryCount": 150,
"size": 3000000,
"unpackedSize": 60000000
},
"warn": {
"entryCount": 100,
"size": 300000,
"unpackedSize": 6000000
}
}
}
}
```
Basic budgets output:
For a task:
- successful: if `fail` threshold has not been exceeded
- otherwise the task has failed
For a threshold:
- successful if all metrics are under their maximum value
- otherwise it has failed
So a task can lead to an error, a warning or an information.
Thresholds can only be passed or failed.
**List of all metrics per plugin**
| Plugin | Key | Metric | Unit |
|:--------------------:|:----------------------------:|:-------------------:|:----------------------------------------------------:|
| Code duplication | code-duplication | percentageTokens | percentage of duplicated tokens |
| | | percentage | percentage of duplicated lines |
| Exact version | dependencies-exact-version | dependencies | number of range version in dependencies |
| | | devDependencies | number of range version in dev dependencies |
| Security audit | security-audit | critical | number of critical vulnerabilities |
| | | high | number of high vulnerabilities |
| | | moderate | number of moderate vulnerabilities |
| | | low | number of low vulnerabilities |
| | | info | number of info |
| Project's size | project-size | entryCount | number of files |
| | | size | size in bytes (only files in final bundle) |
| | | unpackedSize | unpacked size in bytes (only files in final bundle) |
| Dependencies updates | updates | major | number of major updates |
| | | minor | number of minor updates |
| | | patch | number of patch |
| Check dependencies | dependencies-check | missing | number of missing dependencies |
| | | dependencies | number of unused dependencies |
| | | devDependencies | number of unused dev dependencies |
| Dependencies size | dependencies-size | dependencies | number of all dependencies |
| | | directDependencies | number of direct dependencies |
| | | weight | total weight of node_modules folder (production) |
| | | depth | maximum dependencies tree's depth (production) |
| Require time | require-time | entrypointTime | loading time of the entrypoint : require('myModule') |
## CI/CD
Qualscan can be easily integrated with any CI pipeline.
You can look at this [basic example with github actions](https://github.com/wallet77/qualscan/blob/main/.github/workflows/node.js.yml).
To see a typical output you can have a look at this page: [actions page](https://github.com/wallet77/qualscan/runs/1511486101?check_suite_focus=true), and click on step "run the qualscan tool".
Basic CI output with Github actions:
## Compatibility
| Version | Supported | Tested |
|:-------------:|:-------------:|:--------------:|
| 20.x | yes | yes |
| 18.x | yes | yes |
| 16.x | yes | yes |
## Test
```bash
$ npm test
```
Run with coverage
```bash
$ npm run coverage
```
Coverage report can be found in coverage/.
## License
MIT