npm package: @sam.mills/eslint-config
Description: Personalised ESLint Configuration
Author: Sam
Latest version: 1.0.1

# Eslint Config

An opinionated custom ESLint configuration since 2019 with rigid rules for spacing, bracket and comma usage.
This ESLint configuration extends the `eslint:recommended` preset. Justifications for the ruleset can be found on my
[blog](https://sam.mills.lu/posts/eslint-style-guide/), the emphasis on the chosen rule values are to ensure readability
and consistency.

Notable rule values include:

* Indentation: 4 spaces.
* Quotes: double.
* Commas: always after and multiline dangling.
* Semi colons: always.
* Line length: comments and code, 120 characters.
* Brace style: stroustrup.
* Operator newlines: always before.
* One variable per line.
* Spaces around operators.

# Install

First ensure Node.js and the Node Package Manager (NPM) is installed on the machine and open a terminal within the root
directory of the project that will have ESLint and this configuration installed and applied, then install this
configuration module from NPM:

```shell
npm install @sam.mills/eslint-confg --save-dev
```

The `eslint` module is marked as a peer dependency and should be installed automatically alongside the configuration
module in newer versions of NPM (`>=8`), this simplifies the installation process such that installing and updating the
configuration module will install or update the `eslint` module version.

Finally, create an `.eslintrc.json` file within the project root directory, and extend the default configuration:

```json
{
    "root": true,
    "env": {
        "node": true,
        "mocha": true
    },
    "parserOptions": {
        "ecmaVersion": "latest"
    },
    "extends": [
        "@sam.mills/eslint-config/default"
    ]
}
```

The `.eslintrc.json` file is used to inform the `eslint` module which linting rules should be applied, as well as
supplementary information about the environment, including the European Computer Manufacturers Association (ECMA)
Script (ECMAScript/ECMA-262/ES) version, runtime environment, and the use of testing frameworks.

It is recommended to use a JavaScript Object Notation (JSON) format instead of a JavaScript (JS) file for configuration
values to reduce risk of unexpected code execution and to benefit from editor schema validation.

The configuration provided is intended for a Node.js environment with the `mocha` testing framework, with JavaScript
versions ES6 (ES2015) to ES12 (ES2021). TypeScript is not supported by the provided configuration, but could be easily
modified to do so.

## IDE Integration: Editor Config File

To assist the Integrated Development Environment (IDE) with application of certain rules, a `.editorconfig` file can
be included:

```editorconfig
# editorconfig.org
root = true

[*]
end_of_line = lf
charset = utf-8
max_line_length = 120

# Whitespace Control
insert_final_newline = true
trim_trailing_whitespace = true

# Indentation Style
indent_style = space
indent_size = 4
```

The editorconfig file will enforce the following rules across all files (regardless of file extension):

* Unix-style line endings.
* 8-bit Unicode Transformation Format (UTF-8) character encoding.
* Max line length: 120 characters.
* Ensure blank line at the end of the file.
* Ensure no trailing whitespace.
* Ensure indents are always 4 spaces, and not using tab.

Once created or updated, the IDE may need to restart in order to read and apply the editorconfig.

## ESLint Ignore

An [ignore file](https://eslint.org/docs/user-guide/configuring/ignoring-code) can be included at `.eslintignore`
or within the `package.json` file itself, consisting of a list of files for which ESLint should not apply.

Default rules:

* Dot-files (files and folders beginning with a period: `.`)
* Node Modules (`./node_modules`).

If dot-files are required to be linted, then they should be added to the list, preceded with an exclamation-mark: `!`,
akin to the [`.gitignore` syntax](https://git-scm.com/docs/gitignore).

Proposed `.eslintignore` file:

```ignorelang
build/
coverage/
dist/
doc/
logs/
out/
```

## NPM Scripts

For convenience, ESLint commands can be declared within the `package.json` file and executed with `npm run`. Notation
for script naming is recommended as `${script}:${action}` where `script` defines the script, e.g. `lint` and `action`
defines the activity that the script will perform:

* `lint`: Performs default linting of the code, flags all errors and warnings.
* `lint:config`: Returns the config for a given file.
* `lint:fix`: Performs linting and fixing where possible. Unfixable errors and warnings are still flagged.

An example `package.json` script object is provided:

```json
{
    "lint": "eslint .",
    "lint:config": "eslint --print-config src/index.js",
    "lint:fix": "eslint . --fix"
}
```

# Usage

ESLint is used to find errors and warnings within JavaScript code, depending on a given ruleset, log or fix
them automatically. Within the NPM Scripts section, example commands are defined.

To process files and fix ESLint problems automatically without the NPM script defined:

```shell
eslint . --fix
```

To process files and fix ESLint problems automatically with the defined NPM script:

```shell
npm run lint:fix
```

Use of the NPM script is preferred for reducing human error and enabling compatibility with IDEs that prevent execution
of non-scoped commands.