@studyportals/code-style

CodeStyle

The purpose of this repository is to provide standardized configuration files for the most common linters we use in Studyportals repositories. The main usage is in Super-Linter, which uses these configuration files to run the most important linters on most of our repositories.

Please send pull requests to @stefanklokgieters if you think you want to suggest changes. Never publish changes on NPM without a approval...

Table of Contents

• Install
• Linters
  • ESLint
  • TSLint
  • StyleLint
  • SCSSLint
  • PHP Code Sniffer
  • PHPMD
• Best Practices

Install

You can add CodeStyle as a dependency to your project by running the following command:

npm install @studyportals/code-style --save-dev

Linters

ESLint

ESLint is a linter for JavaScript, as well as TypeScript code. It can help find and fix potential problems in your code. When you install the CodeStyle package you can simply extend from the ESLint configuration file inside it.

// package.json
"eslintConfig": {
    "extends": "./node_modules/@studyportals/code-style/.eslintrc.js",
    "parserOptions": {
        "sourceType": "module"
    }
}

Global variables

When global variables are used in different files than they we're defined in, ESLint will see it as an undefined variable. To solve this problem, you can define the global variables at the top of your file like so:

/* global var1, var2, var3 */

To avoid this you can define your project's global variables in a custom configuration.

Examples

Overriding Rules

The example below demonstrates how you can override an existing rule in your .eslintrc.js.

module.exports = {
  extends: "./node_modules/@studyportals/code-style/.eslintrc.js",
  rules: {
    "@typescript-eslint/array-type": [
      "error",
      {
        default: "generic",
      },
    ],
  },
};

You can read more about overriding rules here.

Ignoring Files

The example below demonstrates how you can ignore files in your .eslintrc.js.

module.exports = {
  extends: "./node_modules/@studyportals/code-style/.eslintrc.js",
  ignorePatterns: ["**/tests/"],
};

Otherwise, you can ignore these files by appending them to your .eslintignore. You can read more about ignoring files here.

StyleLint

StyleLint is our main linter for all styling related files. It can read all types of style related syntax, like SCSS, Sass, Less and SugarSS. When you install the CodeStyle package you can simply extend from the StyleLint configuration file inside it.

// .stylelintrc.json
{
  "extends": "./node_modules/@studyportals/code-style/.stylelintrc.json"
}

Examples

Overriding Rules

The example below demonstrates how you can override an existing rule in your .stylelintrc.json.

{
  "extends": "./node_modules/@studyportals/code-style/.stylelintrc.json",
  "rule-empty-line-before": [
    "always",
    {
      "except": "first-nested"
    }
  ]
}

Ignoring Files

The example below demonstrates how you can ignore files in your .stylelintrc.json. However, StyleLint recommends you do so with a .stylelintignore, instead. You can read more about this here.

{
  "extends": "./node_modules/@studyportals/code-style/.stylelintrc.json",
  "ignoreFiles": ["node_modules/", "**/*.js"]
}

PHP Code Sniffer

PHP Code Sniffer is a linter for PHP files. It can both detect and fix coding standard violations. PHP Code Sniffer can be run from the command line, where the configuration can be referenced.

phpcs-run --standard=./node_modules/@studyportals/code-style/phpcs.xml ./

Examples

Overriding Rules

The example below demonstrates how you can override an existing rule in your phpcs.xml to exclude it.

<?xml version="1.0"?>
<ruleset name="Custom">
    <rule ref="./node_modules/@studyportals/code-style/phpcs.xml">
        <exclude name="Generic.Files.LineEndings"/>
    <rule/>
</ruleset>

Ignoring Files

The example below demonstrates how you can ignore files in your phpcs.xml

<?xml version="1.0"?>
<ruleset name="Custom">
    <rule ref="./node_modules/@studyportals/code-style/phpcs.xml" />
    <exclude-pattern>tests/**/*.php</exclude-pattern>
</ruleset>

PHPMD

PHPMD (or PHP Mess Detector) is a linter for PHP files. It takes a given PHP source code base and look for several potential problems within that source. When you install the CodeStyle package you can reference the PHPMD configuration file inside it.

<!-- phpmd.xml -->
<rule ref="./node_modules/@studyportals/code-style/phpmd.xml" />

Examples

Overriding Rules

The example below demonstrates how you can override an existing rule in your phpmd.xml to exclude it.

<?xml version="1.0"?>
<ruleset name="Custom">
    <rule ref="./node_modules/@studyportals/code-style/phpcs.xml">
        <exclude name="Generic.Files.LineEndings"/>
    <rule/>
</ruleset>

Ignoring Files

The example below demonstrates how you can ignore files in your phpmd.xml

<?xml version="1.0"?>
<ruleset name="Custom">
    <rule ref="./node_modules/@studyportals/code-style/phpmd.xml" />
    <exclude-pattern>tests/**/*.php</exclude-pattern>
</ruleset>

PHPStan

PHP Static Analysis Tool is a linter for PHP files. It can discover bugs in the code without running it!. PHPStan can be run from the command line, where the configuration can be referenced. phpstan.neon configuration from the code style can be included as follows:

includes:
  - ./node_modules/@studyportals/code-style/phpstan.neon

Command to run the phpstan

phpstan analyse -c phpstan.neon

Overriding Rules

The example below demonstrates how you can override an existing rule in your phpstan.neon.

includes:
  - ./node_modules/@studyportals/code-style/phpstan.neon
  - phpstan-baseline.neon
parameters:
  level: 8

Ignoring Files

The example below demonstrates how you can ignore files in your phpstan.xml

includes:
  - ./node_modules/@studyportals/code-style/phpstan.neon
  - phpstan-baseline.neon
parameters:
  excludePaths:
    - Modules/RankingXDiscipline/ChartBase/rankings_disciplines.php
    - TestSuites\PHPUnit\Integration\Router\Handlers\Error\DebugErrorHandlerTest.php
    - TestSuites\PHPUnit\Integration\Router\Handlers\Error\DebugXhrErrorHandlerTest.php
    - TestSuites\PHPUnit\Integration\Router\IndexTest.php

Best practices

Whitelisting

Whitelisting source folders is the recommended way of specifying which files should be linted in a project. If certain file within the source folders needs to be skipped, that should be done on file level.