Code Standardization for UIC Pharmacy Projects

This project houses the linters and their rules for the code standards of UIC Pharmacy projects, including:

• Editor configuration with EditorConfig (extension)
• Code spell checking with CSpell (extension)
• Commit message linting with commitlint (extension)
• Shell script linting with ShellCheck (extension)
• Stylesheet linting with Stylelint (extension)
• Markdown linting with markdownlint (extension)
• JavaScript and Typescript linting with eslint (extension)
• YAML linting with yamllint
• Also includes check-node-version

We use these tools by setting up simple scripts that run these tests, which are correspondingly ran in our CI/CD pipelines, such as GitHub Actions. But installing the extensions in VS Code will additionally help you get instant feedback from the linting in your editor! You're welcome!

Usage

Install this package as a dev dependency in your project:

npm install -D uicpharm/standardization

Then you can hook into as many of these tools as applicable. Typically this is done by creating a local config file that uses the uicpharm/standardization one, and setting up a script in package.json.

EditorConfig

EditorConfig provides editor configurations that are compatible with a large variety of editors.

Create a symlink to the .editorconfig file in the root of your project:

ln -s ./node_modules/@uicpharm/standardization/.editorconfig

Code Spell Checking

CSpell spell checks content in your code without getting tripped up by programming expressions.

Create a file called .cspell.json in your project similar to this:

{
   "import": [ "@uicpharm/standardization/.cspell.json" ],
   "useGitignore": true
}

Then add a script in package.json similar to this:

"scripts": {
   "cspell": "cspell . --show-suggestions --no-progress"
}

Commit Message Linting

Using commitlint helps ensure we have well formed, thought out, semantic commit messages.

Create a file called .commitlintrc.json in your project similar to this:

{
   "extends": [ "@uicpharm/standardization/commitlint.config.js" ]
}

Then add a script in package.json, providing the first commit hash to begin linting from. For example, if the commit hash was a1b2c3d4e5:

"scripts": {
   "commitlint": "commitlint --from a1b2c3d4e5",
}

Shell Script Linting

ShellCheck will lint your shell scripts! No additional configuration is necessary.

Add a script in package.json similar to this:

"scripts": {
   "shellcheck": "shellcheck **/*.sh"
}

Stylesheet Linting

Stylelint will lint both CSS and SCSS stylesheets.

Create a file called .stylelintrc.json in your project similar to this:

{
   "extends": "./node_modules/@uicpharm/standardization/.stylelintrc.json"
}

Then add a script in package.json in your project similar to this:

"scripts": {
   "stylelint": "stylelint **/*.css **/*.scss"
}

Markdown Linting

Using markdownlint helps ensure we have consistent Markdown conventions.

Create a file called .markdownlint.json in your project similar to this:

{
   "extends": "@uicpharm/standardization/.markdownlint.json"
}

Then add a script in package.json in your project similar to this:

"scripts": {
   "markdownlint": "markdownlint **/*.md --ignore node_modules"
}

JavaScript and TypeScript Linting

Using eslint is critical to catch programming errors and maintain better coding conventions in JavaScript and TypeScript.

Create a file called .eslintrc.json in your project similar to this:

{
   "extends": "./node_modules/@uicpharm/standardization/.eslintrc.js",
}

Then add a script in package.json in your project similar to this:

"scripts": {
   "eslint": "eslint ."
}

YAML Linting

It doesn't lint to specific YAML schemas by default, but even basic YAML linting with yamllint is helpful to catch errors. No configuration is required, although you can make one if you want.

When you create the script in package.json, note that it will ignore dot-files and dot-folders. So, if you want it to lint GitHub workflows, you may want something like this:

"scripts": {
   "yamllint": "yamllint **/*.yml .*/**/*.yml --ignore=node_modules",
}

Checking the Node Version

Checking the Node version helps ensure that builds are not executed when the right Node can't be set up for some reason. No configuration is needed, and usually the command is added as a test script in package.json.

"scripts": {
   "check-node": "check-node-version --node 20.10.0 --npm 10.2.3",
   "test": "npm run check-node"
}

Putting it all together

Once you have all the desired configs and scripts for individual linting, combine them in the test and standards scripts in package.json. These 2 scripts are executed by our linting and testing workflows by convention.

For instance, if you're using all of the tools, your scripts may look like this:

"scripts": {
   "standards": "npm run eslint && npm run stylelint && npm run shellcheck && npm run yamllint && npm run markdownlint && npm run cspell && npm run commitlint",
   "test": "npm run check-node"
}

These are just recommendations, or starting points, and you can add or subtract to these as needed based on a specific project's needs. For instance, your test script will likely include other code tests, and your standards script may also do TypeScript type checking with a script like tsc --noEmit or similar.