Static Analysis tooling 🛠
Tags: opensource, git, codequality
Published: 2021-11-06 00:58:04

## Introduction

It's easy to forget that people have different ways to write their code, from indentation, writing conditional statements, to choosing what type of quotes to use for strings. While this is trivial when working on personal projects, it is another story for projects with different people simultaneously working on a single code base. Unable to agree on a coding style often leads to problems reviewing pull requests, with developers/project maintainers spending countless hours searching for formatting issues instead of focusing on the logic.

With this in mind, open-source projects need to include static analysis tooling, as they help improve code maintainability by spotting suspicious coding constructs or alerting us to common errors. 

## Choosing the right tool 🔍

For my static site generator, which is written in JavaScript, I have selected [Prettier](https://prettier.io/) and [ESLint](https://eslint.org/) as the formatting and styling guide tools. I chose them due to their popularity amongst other developers, with detailed documentation and high customizability. Also, I have been using Prettier for a while as a VS Code extension, so it would be nice to learn more about it.

## Using Prettier 🎨

To set up Prettier, start by installing the tool using [npm](https://www.npmjs.com/package/prettier):

```bash
npm install --save-dev --save-exact prettier
```

Then, follow the instructions from the Prettier [docs](https://prettier.io/docs/en/install.html) and create 2 files: `.prettierrc` and `.prettierignore`

* `.prettierrc` is where you will set all the configuration options for your Prettier formatting.
* `.prettierignore` lets the Prettier CLI and editors know which files to **not** format. 

Finally, add the necessary scripts to `package.json`:

```js
{
  // ...
  "scripts": {
    "prettier": "prettier --write \"./**/*.{md,jsx,json,html,css,js,yml}\"",
    "prettier-check": "prettier --check \"./**/*.{md,jsx,json,html,css,js,yml}\""
  }
  // ...
}
```

## Using ESLint 🧪

To set up ESLint, start by installing the tool using [npm](https://www.npmjs.com/package/eslint):

```bash
npm install eslint --save-dev
```

After finishing the installation, follow by setting up a configuration file, which you can do with:

```bash
npx eslint --init
```

You should ended up with something like this:

```json
module.exports = {
  env: {
    commonjs: true,
    es2021: true,
    node: true,
  },
  extends: ['eslint:recommended', 'prettier'],
  parserOptions: {
    ecmaVersion: 13,
  },
  rules: {
    semi: ['error', 'always'],
    quotes: ['error', 'double'],
  },
};
```

The configuration file is where you can customize the validation rules based on the project. For more information about the rules, using plugins, or adding shared settings, refer to the ESLint configuration [docs](https://eslint.org/docs/user-guide/configuring/).

Finally, add the necessary scripts to `package.json`:

```js
{
  // ...
  "scripts": {
    "eslint": "eslint --config .eslintrc.js",
    "eslint-fix": "eslint --config .eslintrc.js --fix",
    "lint": "npm run eslint",
  },
  // ...
}
```

## Editor Integration 💻

Running static analysis tools at build time (i.e., using our scripts) is great since we can automate it. However, it would be nice to have a way to integrate them into our editor or IDE so that we can enjoy the benefits while writing code.

My solution is to create a `.vscode/` folder that contains `settings.json`, which directly configures the VSCode editor settings, and `extensions.json`, which stores ESLint and Prettier as the recommended extensions.

## Adding a pre-commit hook 🎣

Lastly, how can we deal with forgetful developers? The answer: adding a Git pre-commit hook. The hook will run your source code formatter on any changes that are being committed, preventing formatting errors before the developer makes a pull request. 

For this task, I'll be using [husky](https://typicode.github.io/husky/#/) and [pretty-quick](https://www.npmjs.com/package/pretty-quick). `husky` is a package for defining and executing git hooks, while `pretty-quick` is used to run Prettier formatting against your staged files.

First, start by installing `husky` and `pretty-quick`:

```bash
npx husky-init && npm install
npm install --save-dev prettier pretty-quick
```

This will setup `husky`, modify `package.json` and create a sample `pre-commit` hook that you can edit. 

Inside `package.json`, modify the `pre-commit` script to use `pretty-quick`:

```js
{
  // ...
  "scripts": {
    "pre-commit": "pretty-quick --staged"
  },
  // ...
}
```

After that, add the following code to `/.husky/pre-commit`:

```bash
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

echo '🐶 Checking your commit...'
npm run pre-commit || echo '❌ Build failed. Please fix the error(s) showed above.'
```

And that's it! Every time you make a commit, the pre-commit hook will make sure to format the code using the configurations from `.prettierrc`.

Cheers! 🍻