@infernodesign/eslint-config 1.0.0

package/README.md

@@ -0,0 +1,743 @@
+# @infernodesign/eslint-config
+
+Shared ESLint flat config presets for Inferno Design projects.
+
+- Autofix for formatting (aimed to be used standalone **without** Prettier)
+- Reasonable best practices and only one line of config.
+- Designed to work with TypeScript, JSX, Vue, JSON, YAML, Toml, Markdown, etc. Out-of-box.
+- Uses the [ESLint Flat Config](https://eslint.org/docs/latest/use/configure/configuration-files-new) for easy compilation.
+- Optional [React](#react), [Next.js](#nextjs), [Svelte](#svelte), [UnoCSS](#unocss), [Astro](#astro), [Solid](#solid) support.
+- Optional [formatters](#formatters) support for formatting CSS, HTML, XML, etc.
+- **Style principle**: Minimal for reading, stable for diff, consistent
+  - Sorted imports, dangling commas
+  - Single quotes, no semi
+  - Using [ESLint Stylistic](https://github.com/eslint-stylistic/eslint-stylistic)
+- Respects `.gitignore` by default
+- Requires ESLint v9.5.0+
+
+## Setup
+
+> [!NOTE]
+> Since this package is hosted in the GitHub Packages registry and is private to just Inferno Design, you must configure your `.npmrc` file to access the private registry.
+
+### `.npmrc` Configuration
+
+To configure your `.npmrc` file, add the following line:
+
+```ini
+//npm.pkg.github.com/:_authToken=$GITHUB_TOKEN
+@infernodesign:registry=https://npm.pkg.github.com/
+```
+
+Then, create an environment variable `GITHUB_TOKEN` with a personal access token that has the `read:packages` scope. Alternatively, you can replace `$GITHUB_TOKEN` with your personal access token directly in the `.npmrc` file. Make sure you don't commit this file to VCS to avoid exposing your token.
+
+### Registry Configuration
+
+Alternatively, you can configure the registry for the `@infernodesign` packages registry scope using the following command:
+
+```bash
+pnpm config set @infernodesign:registry https://npm.pkg.github.com/
+```
+
+This command sets the registry for the `@infernodesign` scope to the GitHub Packages registry.
+
+### Authentication
+
+Ensure that your authentication is set up correctly to access the packages. You can add your GitHub token to the `.npmrc` file as shown above or use the following command:
+
+```bash
+pnpm config set //npm.pkg.github.com/:_authToken <your-personal-access-token>
+```
+
+Replace `<your-personal-access-token>` with your actual GitHub personal access token.
+
+## Usage
+
+### Quick Start
+
+To quickly set up ESLint with the Inferno Design configuration or migrate from the legacy config to the new flat config, run the following CLI command in the root of your project:
+
+```bash
+pnpm dlx @infernodesign/eslint-config@latest
+```
+
+### Manual Installation
+
+To manually install and configure ESLint with the Inferno Design configuration, follow these steps:
+
+Install the necessary dependencies:
+
+```shell
+pnpm i -D eslint @infernodesign/eslint-config
+```
+
+Create a `eslint.config.js` in your project root:
+
+```js
+// eslint.config.mjs
+import config from '@infernodesign/eslint-config'
+
+export default config()
+```
+
+That's it! You can now run ESLint in your project:
+
+```shell
+eslint . --fix
+```
+
+<details>
+<summary>
+Combine with legacy config:
+</summary>
+
+To use configs from the legacy `eslintrc` format, use the [`@eslint/eslintrc`](https://www.npmjs.com/package/@eslint/eslintrc) package to convert them to the flat config.
+
+```js
+// eslint.config.mjs
+import { FlatCompat } from '@eslint/eslintrc'
+import config from '@infernodesign/eslint-config'
+
+const compat = new FlatCompat()
+
+export default config(
+  {
+    ignores: [],
+  },
+  // Legacy config
+  ...compat.config( {
+    extends: [
+      'eslint:recommended',
+      // Other extends...
+    ],
+  } )
+  // Other flat configs...
+)
+```
+
+> [!NOTE]
+> `.eslintignore` no longer works in Flat config, see [customization](#customization) for more details.
+
+</details>
+
+### Node Package Scripts
+
+To lint your project, add the following scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  }
+}
+```
+
+### Precommit Hook
+
+To lint your project before committing, use a precommit hook with [husky](https://typicode.github.io/husky/#/):
+
+```bash
+pnpm install husky --save-dev
+pnpx husky install
+pnpx husky add .husky/pre-commit "eslint . --fix && git add ."
+```
+
+This will automatically lint and fix your code before each commit.
+
+## VS Code Support (Autofix on Save)
+
+Install the [VS Code ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint).
+
+Then, add the following settings to your `.vscode/settings.json`:
+
+```json5
+{
+  // Disable the default formatter, use eslint instead
+  "prettier.enable": false,
+  "editor.formatOnSave": false,
+
+  // Autofix on save
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit",
+    "source.organizeImports": "never"
+  },
+
+  // (Optional) Silent the stylistic rules in the IDE, but still autofix them
+  "eslint.rules.customizations": [
+    { "rule": "style/*", "severity": "off", "fixable": true },
+    { "rule": "format/*", "severity": "off", "fixable": true },
+    { "rule": "*-indent", "severity": "off", "fixable": true },
+    { "rule": "*-spacing", "severity": "off", "fixable": true },
+    { "rule": "*-spaces", "severity": "off", "fixable": true },
+    { "rule": "*-order", "severity": "off", "fixable": true },
+    { "rule": "*-dangle", "severity": "off", "fixable": true },
+    { "rule": "*-newline", "severity": "off", "fixable": true },
+    { "rule": "*quotes", "severity": "off", "fixable": true },
+    { "rule": "*semi", "severity": "off", "fixable": true }
+  ],
+
+  // Enable eslint for all supported languages
+  "eslint.validate": [
+    "javascript",
+    "javascriptreact",
+    "typescript",
+    "typescriptreact",
+    "vue",
+    "html",
+    "markdown",
+    "json",
+    "jsonc",
+    "yaml",
+    "toml",
+    "xml",
+    "gql",
+    "graphql",
+    "astro",
+    "svelte",
+    "css",
+    "less",
+    "scss",
+    "pcss",
+    "postcss"
+  ]
+}
+```
+
+## Customization
+
+This package uses the new [ESLint Flat Config](https://eslint.org/docs/latest/use/configure/configuration-files-new). It provides much better organization and composition.
+
+Normally you only need to import the `config` preset:
+
+```js
+// eslint.config.js
+import config from '@infernodesign/eslint-config'
+
+export default config()
+```
+
+And that's it! Or you can configure each integration individually, for example:
+
+```js
+// eslint.config.js
+import config from '@infernodesign/eslint-config'
+
+export default config( {
+  // Type of the project. 'lib' for libraries, the default is 'app'
+  type: 'lib',
+
+  // Enable stylistic formatting rules
+  // stylistic: true,
+
+  // Or, customize the stylistic rules
+  stylistic: {
+    indent: 2, // 4, or 'tab'
+    quotes: 'single', // or 'double'
+  },
+
+  // TypeScript and Vue are auto-detected, you can also explicitly enable them:
+  typescript: true,
+  vue: true,
+
+  // Enable React
+  react: true,
+
+  // Enable Next.js
+  next: true,
+
+  // Disable jsonc and yaml support
+  jsonc: false,
+  yaml: false,
+
+  // `.eslintignore` is no longer supported in Flat config, use `ignores` instead
+  ignores: [
+    '**/fixtures',
+    // ... Additional globs
+  ]
+} )
+```
+
+The `config` factory function accepts any amount of custom config overrides:
+
+```js
+// eslint.config.js
+import config from '@infernodesign/eslint-config'
+
+export default config(
+  {
+    // Configurations for `config`
+  },
+  // ESLint Flat Configs
+  {
+    files: [ '**/*.ts' ],
+    rules: {},
+  },
+  {
+    files: [ '**/*.vue' ],
+    rules: {},
+  },
+)
+```
+
+A more advanced usage, import fine-grained configs and compose them together:
+
+### Advanced Example
+
+Using this style is not recommended as the shared options between configs might need extra care to be consistent.
+
+```js
+// eslint.config.js
+import {
+  combine,
+  comments,
+  ignores,
+  imports,
+  javascript,
+  jsdoc,
+  jsonc,
+  markdown,
+  next,
+  node,
+  react,
+  sortPackageJson,
+  sortTsconfig,
+  stylistic,
+  toml,
+  typescript,
+  unicorn,
+  vue,
+  yaml,
+} from '@infernodesign/eslint-config'
+
+export default combine(
+  combine(),
+  comments(),
+  ignores(),
+  imports(),
+  javascript( /* options */ ),
+  jsdoc(),
+  jsonc(),
+  markdown(),
+  next(),
+  node(),
+  react( /* options */ ),
+  sortPackageJson(),
+  sortTsconfig(),
+  stylistic(),
+  toml(),
+  typescript( /* options */ ),
+  unicorn(),
+  vue(),
+  yaml(),
+)
+```
+
+Refer to the [configs](https://github.com/infernodesign/tooling/tree/main/tooling/eslint/src/configs) and [factory](https://github.com/infernodesign/tooling/tree/main/tooling/eslint/src/factory.ts) source files for more details.
+
+### Plugin Renaming
+
+Since ESLint Flat Config requires explicitly providing the plugin names (instead of the mandatory convention from npm package name), some plugins have been renamed to make the overall scope more consistent and easier to write.
+
+| New Prefix | Original Prefix        | Source Plugin                                                                                                        |
+|------------|------------------------|----------------------------------------------------------------------------------------------------------------------|
+| `import/*` | `import-x/*`           | [eslint-plugin-import-x](https://github.com/un-es/eslint-plugin-import-x)                                            |
+| `next/*`   | `@next/next/*`         | [@next/eslint-plugin-next](https://nextjs.org/docs/pages/building-your-application/configuring/eslint#eslint-plugin) |
+| `node/*`   | `n/*`                  | [eslint-plugin-n](https://github.com/eslint-community/eslint-plugin-n)                                               |
+| `style/*`  | `@stylistic/*`         | [@stylistic/eslint-plugin](https://github.com/eslint-stylistic/eslint-stylistic)                                     |
+| `test/*`   | `vitest/*`             | [eslint-plugin-vitest](https://github.com/veritem/eslint-plugin-vitest)                                              |
+| `test/*`   | `no-only-tests/*`      | [eslint-plugin-no-only-tests](https://github.com/levibuzolic/eslint-plugin-no-only-tests)                            |
+| `ts/*`     | `@typescript-eslint/*` | [@typescript-eslint/eslint-plugin](https://github.com/typescript-eslint/typescript-eslint)                           |
+| `yaml/*`   | `yml/*`                | [eslint-plugin-yml](https://github.com/ota-meshi/eslint-plugin-yml)                                                  |
+
+To override rules, or disable them inline, use the new prefix:
+
+```diff
+-// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
++// eslint-disable-next-line ts/consistent-type-definitions
+type foo = { bar: 2 }
+```
+
+> [!NOTE]
+> This preset will automatically rename the plugins for your custom configs. Use the original prefix to override the rules directly.
+
+### Rules Overrides
+
+Certain rules would only be enabled for specific files. For example, `ts/*` rules would only be enabled in
+`.ts` files and `vue/*` rules would only be enabled in `.vue` files. To override the rules, specify the file extension:
+
+```js
+// eslint.config.js
+import config from '@infernodesign/eslint-config'
+
+export default config(
+  {
+    typescript: true,
+    vue: true
+  },
+  {
+    // Remember to specify the file glob here, otherwise it might cause the vue plugin to handle non-vue files
+    files: [ '**/*.vue' ],
+    rules: {
+      'vue/operator-linebreak': [ 'error', 'before' ],
+    },
+  },
+  {
+    // Without `files`, they are general rules for all files
+    rules: {
+      'style/semi': [ 'error', 'never' ],
+    },
+  }
+)
+```
+
+Use the provided `overrides` options in each integration to make overrides easier:
+
+```js
+// eslint.config.js
+import config from '@infernodesign/eslint-config'
+
+export default config( {
+  typescript: {
+    overrides: {
+      'ts/consistent-type-definitions': [ 'error', 'interface' ],
+    },
+  },
+  vue: {
+    overrides: {
+      'vue/operator-linebreak': [ 'error', 'before' ],
+    },
+  },
+  yaml: {
+    overrides: {
+      // ...
+    },
+  },
+} )
+```
+
+### Config Composer
+
+The factory function `config()` returns a [`FlatConfigComposer` object from
+`eslint-flat-config-utils`](https://github.com/antfu/eslint-flat-config-utils#composer) where you can chain the methods to compose the config more flexibly.
+
+```js
+// eslint.config.js
+import config from '@infernodesign/eslint-config'
+
+export default config()
+  .prepend(
+  // some configs before the main config
+  )
+// overrides any named configs
+  .override(
+    'config/imports',
+    {
+      rules: {
+        'import/order': [ 'error', { 'newlines-between': 'always' } ],
+      }
+    }
+  )
+// rename plugin prefixes
+  .renamePlugins( {
+    'old-prefix': 'new-prefix',
+  // ...
+  } )
+// ...
+```
+
+### Vue
+
+Vue support is detected automatically by checking if
+`vue` is installed in your project. To explicitly enable/disable it:
+
+```js
+// eslint.config.js
+import config from '@infernodesign/eslint-config'
+
+export default config( {
+  vue: true
+} )
+```
+
+#### Vue 2
+
+Limited support for Vue 2 is available since it has [reached EOL](https://v2.vuejs.org/eol/). To use Vue 2, configure it manually by setting
+`vueVersion` to `2`:
+
+```js
+// eslint.config.js
+import config from '@infernodesign/eslint-config'
+
+export default config( {
+  vue: {
+    vueVersion: 2
+  },
+} )
+```
+
+### Optional Configs
+
+Some optional configs are available for specific use cases. Their dependencies are not provided by default.
+
+#### Formatters
+
+Use external formatters to format files that ESLint can't handle yet (`.css`, `.html`, etc). Powered by [`eslint-plugin-format`](https://github.com/antfu/eslint-plugin-format).
+
+```js
+// eslint.config.js
+import config from '@infernodesign/eslint-config'
+
+export default config( {
+  formatters: {
+    /**
+     * Format CSS, LESS, SCSS files, also the `<style>` blocks in Vue
+     * By default uses Prettier
+     */
+    css: true,
+
+    /**
+     * Format HTML files
+     * By default uses Prettier
+     */
+    html: true,
+
+    /**
+     * Format Markdown files
+     * Supports Prettier and dprint
+     * By default uses Prettier
+     */
+    markdown: 'prettier'
+  }
+} )
+```
+
+Then, install the required dependencies:
+
+```shell
+pnpm i -D eslint-plugin-format
+```
+
+#### Next.js
+
+To enable Next.js support, explicitly turn it on:
+
+```js
+// eslint.config.js
+import config from '@infernodesign/eslint-config'
+
+export default config( {
+  next: true,
+} )
+```
+
+Then, install the required dependencies:
+
+```shell
+pnpm i -D @next/eslint-next-plugin
+```
+
+#### React
+
+To enable React support, explicitly turn it on:
+
+```js
+// eslint.config.js
+import config from '@infernodesign/eslint-config'
+
+export default config( {
+  react: true,
+} )
+```
+
+Then, install the required dependencies:
+
+```shell
+pnpm i -D @eslint-react/eslint-plugin eslint-plugin-react-hooks eslint-plugin-react-refresh
+```
+
+#### Svelte
+
+To enable svelte support, explicitly turn it on:
+
+```js
+// eslint.config.js
+import config from '@infernodesign/eslint-config'
+
+export default config( {
+  svelte: true,
+} )
+```
+
+Then, install the required dependencies:
+
+```shell
+pnpm i -D eslint-plugin-svelte
+```
+
+#### Astro
+
+To enable astro support, explicitly turn it on:
+
+```js
+// eslint.config.js
+import config from '@infernodesign/eslint-config'
+
+export default config( {
+  astro: true,
+} )
+```
+
+Then, install the required dependencies:
+
+```shell
+pnpm i -D eslint-plugin-astro
+```
+
+#### Solid
+
+To enable Solid support, explicitly turn it on:
+
+```js
+// eslint.config.js
+import config from '@infernodesign/eslint-config'
+
+export default config( {
+  solid: true,
+} )
+```
+
+Then, install the required dependencies:
+
+```shell
+pnpm i -D eslint-plugin-solid
+```
+
+#### UnoCSS
+
+To enable UnoCSS support, explicitly turn it on:
+
+```js
+// eslint.config.js
+import config from '@infernodesign/eslint-config'
+
+export default config( {
+  unocss: true,
+} )
+```
+
+Then, install the required dependencies:
+
+```shell
+pnpm i -D @unocss/eslint-plugin
+```
+
+### Type-Aware Rules
+
+You can optionally enable the [type-aware rules](https://typescript-eslint.io/linting/typed-linting/) by passing the options object to the
+`typescript` config:
+
+```js
+// eslint.config.js
+import config from '@infernodesign/eslint-config'
+
+export default config( {
+  typescript: {
+    tsconfigPath: 'tsconfig.json',
+  },
+} )
+```
+
+### Command-Line Interface (CLI)
+
+Powered by [`eslint-plugin-command`](https://github.com/antfu/eslint-plugin-command). It is not a typical rule for linting, but an on-demand micro-codemod tool that triggers by specific comments.
+
+For a few triggers, for example:
+
+- `/// to-function` - converts an arrow function to a normal function
+- `/// to-arrow` - converts a normal function to an arrow function
+- `/// to-for-each` - converts a for-in/for-of loop to `.forEach()`
+- `/// to-for-of` - converts a `.forEach()` to a for-of loop
+- `/// keep-sorted` - sorts an object/array/interface
+- ... etc. - refer to the [documentation](https://github.com/antfu/eslint-plugin-command#built-in-commands)
+
+You can add the trigger comment one line above the code you want to transform, for example (note the triple slash):
+
+<!-- eslint-skip -->
+
+```ts
+/// to-function
+const foo = async ( msg: string ): void => {
+  console.log( msg )
+}
+```
+
+Will be transformed to this when you hit save with your editor or run `eslint . --fix`:
+
+```ts
+async function foo( msg: string ): void {
+  console.log( msg )
+}
+```
+
+The command comments are usually one-off and will be removed along with the transformation.
+
+### Editor Specific Disables
+
+Some rules are disabled when inside ESLint IDE integrations, namely [`unused-imports/no-unused-imports`](https://www.npmjs.com/package/eslint-plugin-unused-imports) [`test/no-only-tests`](https://github.com/levibuzolic/eslint-plugin-no-only-tests).
+
+This is to prevent unused imports from getting removed by the IDE during refactoring to get a better DX. Those rules will be applied when running ESLint in the terminal or [Lint Staged](#lint-staged). To disable this behavior:
+
+```js
+// eslint.config.js
+import config from '@infernodesign/eslint-config'
+
+export default config( {
+  isInEditor: false
+} )
+```
+
+### Lint Staged
+
+To apply linting and auto fixing before every commit, add the following to your `package.json`:
+
+```json
+{
+  "simple-git-hooks": {
+    "pre-commit": "pnpm lint-staged"
+  },
+  "lint-staged": {
+    "*": "eslint --fix"
+  }
+}
+```
+
+Then, install the required dependencies:
+
+```shell
+pnpm i -D lint-staged simple-git-hooks
+
+# to activate the hooks
+npx simple-git-hooks
+```
+
+## View what rules are enabled
+
+Use the [`@eslint/config-inspector`](https://github.com/eslint/config-inspector) visual tool to view the enabled rules in your project and applied to each file.
+
+In the project root that contains the `eslint.config.js`file, run:
+
+```shell
+pnpx @eslint/config-inspector
+
+# or specify the config file
+pnpx @eslint/config-inspector  --config ./eslint.config.js
+```
+
+## License
+
+Licensed under the [MIT License](./LICENSE).
+
+## Credits
+
+- Inspired by [Antfu's eslint-config](https://github.com/antfu/eslint-config)