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
  • Stylelint
  • PHP_CodeSniffer
  • PHP Mess Detector
  • PHPStan
• Running Super-Linter Locally
• 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 the ESLint configuration inside your .eslintrc.yml.

extends: "./node_modules/@studyportals/code-style/.eslintrc.js"

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.

Local Linting

Visual Studio Code

To enable linting locally, you can follw the steps below.

1. Install the ESLint plugin from the Microsoft Extensions Marketplace in VSCode
2. Open your user settings file by hitting Ctrl + Shift + P and search for Preferences: Open Settings (JSON)
3. Add the following JSON snippet to the settings.json

  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true,
  },
  "eslint.validate": [
    "javascript",
    "typescript",
  ]

4. Restart the TypeScript Language Server by hitting Ctrl + Shift + P and running TypeScript: Restart TS Server

With these changes in place, whenever you save any changes, some errors are automatically resolved. For those that aren't you will receive errors or warnings that you can act upon.

PhpStorm

Follow the official documentation on how to configure ESLint with PhpStorm.

Examples

Overriding Rules

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

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.yml.

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"
}

Local Linting

Visual Studio Code

To enable linting locally, you can follow the steps below.

1. Install the Stylelint plugin from the Microsoft Extensions Marketplace in VSCode
2. Open your user settings file by hitting Ctrl + Shift + P and search for Preferences: Open Settings (JSON)
3. Add the following JSON snippet to the settings.json

  "editor.codeActionsOnSave": {
    "source.fixAll.stylelint": true,
  }

With these changes in place, whenever you save any changes, some errors are automatically resolved. For those that aren't you will receive errors or warnings that you can act upon.

PhpStorm

Follow the official documentation on how to configure Stylelint with PhpStorm.

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_CodeSniffer

PHP_CodeSniffer is a linter for PHP files. It can both detect and fix coding standard violations. PHP_CodeSniffer can be run from the command line, where the configuration can be referenced. You can extend the PHP_CodeSniffer configuration from the CodeStyle package.

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

Local Linting

Visual Studio Code

To enable linting locally, you can follow the steps below.

1. Install the phpcs plugin from the Microsoft Extensions Marketplace in VSCode.
2. Open your user settings file by hitting Ctrl + Shift + P and search for Preferences: Open Settings (JSON)
3. Add the following JSON snippet to the settings.json

  "phpcs.executablePath": "./vendor/bin/phpcs" // or "./vendor/bin/phpcs.bat"
  "phpcs.ignorePatterns": [ "*/vendor/*" ]

PhpStorm

Follow the official documentation on how to configure PHP_CodeSniffer with PhpStorm.

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>

PHP Mess Detector

PHP Mess Detector (PHPMD) 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" />

Local Linting

Visual Studio Code

To enable linting locally, you can follow the steps below.

1. Install the PHP Mess Detector plugin from the Microsoft Extensions Marketplace in VSCode.
2. Open your user settings file by hitting Ctrl + Shift + P and search for Preferences: Open Settings (JSON)
3. Add the following JSON snippet to the settings.json

  "phpmd.rules": "${workspaceFolder}/phpmd.xml",

PhpStorm

Follow the official documentation on how to configure PHPMD with PhpStorm.

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. PHPStan can be run from the command line, where the configuration can be referenced. The phpstan.neon configuration from CodeStyle can be included as follows.

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

To run PHPStan

phpstan analyse -c phpstan.neon

Local Linting

Visual Studio Code

To enable linting locally, you can follow the steps below.

1. Install the phpstan plugin from the Microsoft Extensions Marketplace in VSCode.

PhpStorm

Follow the official documentation on how to configure PHPStan with PhpStorm.

Examples

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

Running Super-Linter Locally

It is possible to run the Super-Linter GitHub workflow using Docker containers. In some cases, this can be useful. To do so, follow the instructions below.

1. Follow the act installation instructions and choose the option that best suits your environment
2. (OPTIONAL) Older versions of Superlinter workflow requires a personal access token to be executed. If the linter workflow you are working on requires it. Follow:

• Create a GitHub access token with the repo scope
• Create a new .secrets file (or equivalent) and add it to your .gitignore
• Append SUPERLINTER=<value> to the .secrets file by pasting the value of the access token created in step 2

3. Add a new script to your package.json called superlinter (or equivalent), which executes the command act workflow_dispatch -W [path-to-linter-workflow] --secret-file [path-to-secret-file] --rm. Omit the --secret-file argument if the workflow does not need it.
4. Ensure that you are logged into the Docker registry by running docker login
5. Run npm run superlinter

[!IMPORTANT]
If you are using Windows (not WSL), you might need to add the argument -P <platform>=<docker-image> when running act. You can identify the platform based on the runs-on property of the job in the linter.yml. For the docker-image, you can select the relevant medium-sized image from the documentation.

It is recommended to read the act documentation.

Best practices

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

Contributing

What the validation harness does and does not check

npm test runs the gates below. Their scope is deliberate and worth stating, because "validate all ESLint rules" can be read much more broadly than is useful:

The harness validates the rules we configure — that each one exists on both supported ESLint lines, is not deprecated, uses a string severity, has schema-valid options, is not set to conflicting severities across our own config objects, and does not double-report against a typescript-eslint extension rule. It validates which rules resolve per file type (.js, .cjs, .mjs, .jsx, .ts, .tsx, .mts, .cts). And it validates coverage of the sets we track: core recommended, typescript-eslint's recommended/recommendedTypeChecked, and @stylistic.

It does not validate the ~230 core and ~150 typescript-eslint rules we deliberately do not configure, and it does not validate rule behaviour — that is the plugins' own test suites' job. Coverage of the sets is what makes a future engine or plugin addition a failing test rather than silent drift.

| Gate | What it protects | |---|---| | validate:deps | Every dependency's eslint peer admits both 9.39.x and 10.x, and every engines.node floor is satisfied by Node 24.15.0 — the exact Node in the Super-Linter image, where eslint-plugin-jsdoc leaves zero margin. | | validate:rules | Rule existence on both engines, deprecation, string severities, option schemas, severity conflicts, core/extension double-reporting, $comment presence, and preset membership. | | validate:coverage | Two-sided must-contain / must-not-contain assertions per file type. The only gate that can catch a mis-scoped base config — a snapshot would record the broken config as its baseline. | | validate:load | The ESM and CJS entries produce the same config with strictly identical plugin objects. Catches a wrong interop helper, which would otherwise register duplicate plugin state. | | validate:snapshots | ESLint 9.39.5 and 10.9.1 resolve our config identically after a declared, non-growing normalisation, plus drift detection against committed snapshots. | | lint:fixtures | Which rules actually fire, asserted per file against test/expected-violations.json. Also fails if any fixture matches no config object. | | validate:pack (CI) | npm pack + install into throwaway ESM and CJS consumers that declare no plugins of their own. The only gate that catches exports/files mistakes before publish. |

Not applicable here

eslint-doc-generator and RuleTester are deliberately absent. Both exist to support ESLint plugins: the first generates per-rule documentation, the second unit-tests rule implementations. This package is a shareable configuration and authors zero rules, so neither has anything to act on. This is recorded so the gap is not rediscovered and "fixed".

Upgrading to a new ESLint major

Formatting rules live only in configs.stylistic (via @stylistic/eslint-plugin), so ESLint's eventual removal of its frozen core formatting rules is a no-op here. The one manual job is re-deriving src/rules/core-recommended.json — and validate:rules check (h) turns that into a failing test naming every rule the new engine recommends that we have not yet decided about, rather than a silent drift. The same mechanism covers typescript-eslint and @stylistic minors via test/preset-members.json.