Qualscan in action

Detect quality issues in your Javascript project

Introduction

Quality in software engineering can have a huge impact on your business, on your system’s response time, on your infrastructure costs, etc. Surprisingly it’s also one of the most underestimated areas in our industry (in terms of monetary returns and programming time). If you prefer to promote quality over quantity, and if you are looking for a solution to automate the process of checking the quality of your javascript projects then this article might interest you.

Checklist to ensure better code quality

Let’s say you are aware that the quality of your project is important: great! You are probably already using some well-known modules like test automation frameworks, linters, or security audit tools.

All of them can be run with the scripts section in your package.json file. So, in other words, you automatically have a kind of checklist that you launch when it’s necessary (before pushing your commits, before merging a PR, etc).

"scripts": {
  "lint": "mylinter",
  "test": "my test framework",
  "otherTool": "run command",
  ...
  "all": "npm run test && npm run lint && ..."
}

What are the drawbacks of this approach?

First, you are obliged to create “One script to run them all”. It’s not really convenient especially if you want to get errors, to make them all run even if one fails, to run commands simultaneously …

Secondly, you should install some packages globally or locally in every project you manage. For example, say you want to check code duplication, the same module (like jscpd) will be used on every project just with a different configuration for each one.

Finally, you are not able to enable/disable tools on every run, if you want to do so you should create multiple script entries or edit the command each and every time.

Qualscan: the new module to improve javascript quality

Use the “qualscan” module to run your entire checklist with a single command. Qualscan for Quality Scanner is a simple tool, available on npm, to run multiple tasks that will check your code, project structure, dependencies, etc. in terms of quality.

npm install qualscan -g

or

npm install qualscan --save-dev

Then (in your project root directory),

qualscan

Run qualscan on your project

Here is the checklist currently managed by this module:

• linter
• tests
• check package (see @skypack/package-check)
• code duplication (see jscpd)
• dependency updates
• dependency exact version
• dependency security audit
• check dependencies (missing & unused)
• project size (number of files, size of your package, etc)
• dependency size
• require time

If some tasks don’t succeed, they will be marked with a different symbol (‘i’ for information, triangle for warnings, and a red X for errors).

One quality issue has been detected

You can customize qualscan and each task's behaviors with a lot of options. A full list can be seen on the documentation page. Another way to see all the options is to use the -h argument.

qualscan -h

Use configuration file

By default, “qualscan” will try to load .qualscanrc file. If you prefer you can specify the path where the configuration file can be found.

qualscan --c pathToFile/config.json

An example of a configuration file can be found here.

Integrate quality tool in your CI/CD

Qualscan can be linked to any CI pipeline. It basically returns 1 if at least one task has failed, otherwise it returns 0.

Note that it will not stop even if one task has failed. It will run all the tasks regardless of the result of each one, thus you can see all failing tasks in a single build.

A basic example with Github actions:

Note that we should run “qualscan” with the --scriptsoption to prevent the linter and tests from being triggered because we are running them manually in the workflow.

How to fix issues?

Qualscan has one important option to display more information about quality issues. With the --verbose(eventually associated with the option --level) you can display:

• tasks messages: the output of each plugin
• documentation link: to understand how to fix your issue
• a debug command: run it to have more options/details for specific tasks

qualscan --verbose --level error

Javascript quality Score and budget

Qualscan will print a global score, based on the percentage of successful tasks.

In addition to that, you can use the notion of budget, based on the principle of the Webperf performance budget. It will show you all the metrics that are taken into account by the tool to calculate the global score.

Every plugin can have three thresholds (fail, warn, info) and each of them can have multiple metrics. You can use default values or you can choose to override some of them in your .qualscanrcfile.

A task has failed if the fail threshold has been exceeded. If other thresholds are exceeded, then it will change the task indicator (“i” for info and triangle for warning) but the task is nonetheless considered as successful.

Run your own quality tasks (scripts)

Qualscan allows you to run your own scripts present in your package.json file. By default, it will look for test and lint entries. If they are found it will run them. You can disable this behavior by providing your own list of scripts to run.

qualscan --scripts test linter customScript

Conclusion

Qualscan is not the perfect tool to solve all the quality issues of your projects. A lot of areas or not covered here like deep security analysis, performance monitoring, maintainability, etc. But it can help to detect bad practices (and so to reduce bad user experience, bugs, security vulnerabilities, downloading time) before deploying a project on production or before publishing a module on NPM.

What’s really important is that Qualscan is an open-source project and everyone is welcome to participate to create issues, pull requests, feature requests, etc. You can make evolve this tool by adding new features and strengthening its purpose: to improve the quality of javascript projects.

Feel free to participate here.

Sources

wallet77/qualscan

qualscan