@useinsider/eslint-config 1.13.0-beta.4 → 1.13.0-beta.6

package/README.md

@@ -1,97 +1,406 @@
-# ESLint Configurations
+# @useinsider/eslint-config
+
+Shared ESLint 9 flat-config for Insider projects. `useInsider()` takes a single
+scope-keyed config object and returns a `defineConfig([...])` array — one
+entry per file scope you describe. There is no opaque preset list, no
+freeform `config` escape hatch, and no expectation that you spread the result
+into your own array.
+
+The default export is the resolved Promise returned by `useInsider(...)`;
+ESLint 9 awaits it automatically. **Do not `await` it. Do not spread it. Do
+not wrap it in an array.** If you find yourself wanting to append a block,
+that is a sign your scope coverage is incomplete — describe the extra files
+inside `useInsider({...})` instead.
 
 ## Table of Contents
-- [ESLint Configurations](#eslint-configurations)
-  - [Table of Contents](#table-of-contents)
-  - [Prerequisites](#prerequisites)
-  - [Available Presets](#available-presets)
-    - [Vanilla 🍦](#vanilla-)
-    - [Library-specific \& Standalone Configs](#library-specific--standalone-configs)
-    - [Framework-specific](#framework-specific)
-    - [⏳ Upcoming Configurations](#-upcoming-configurations)
-  - [Examples](#examples)
-  - [Troubleshooting](#troubleshooting)
-    - [`Missing dependencies detected:`](#missing-dependencies-detected)
-  - [Contributing](#contributing)
+
+- [Prerequisites](#prerequisites)
+- [Quick start](#quick-start)
+- [Manual setup](#manual-setup)
+  - [Node + TypeScript](#node--typescript)
+  - [Browser + Vue 3 + TypeScript with split tsconfigs](#browser--vue-3--typescript-with-split-tsconfigs)
+  - [Vue 2 + JavaScript with jQuery globals](#vue-2--javascript-with-jquery-globals)
+  - [Strict and spell-checker knobs](#strict-and-spell-checker-knobs)
+- [API reference](#api-reference)
+- [Migrating from v1.x](#migrating-from-v1x)
+- [First lint after install](#first-lint-after-install)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
 
 ## Prerequisites
 
-- NodeJS 20+
+- Node.js 20+
 - ESLint 9+
+- pnpm, npm, or yarn
+
+## Quick start
+
+```bash
+npx @useinsider/eslint-config
+```
+
+The CLI walks an interactive prompt (project type, language, framework, test
+runner, jQuery globals, tsconfig layout), installs every required ESLint
+plugin pinned to the versions this package was built against, and writes a
+starter `eslint.config.mjs` at the project root.
+
+To migrate an existing v1 `eslint.config.{js,mjs,cjs}` or a legacy
+`.eslintrc.{js,cjs}`:
+
+```bash
+npx @useinsider/eslint-config migrate [path]
+```
+
+The migrate flow auto-detects the source format. For flat configs it
+parses the v1 file, prints a summary plus any dropped custom rules, asks
+for confirmation, then rewrites the file in place. For legacy `.eslintrc`
+files it writes a fresh `eslint.config.mjs` next to the original (custom
+rules and non-`@useinsider/eslint-config/*` extends are dropped with a
+loud warning so you can review what changed). The original is backed up
+in both cases as `eslint.config.v1-backup.<ext>` or
+`.eslintrc.v1-backup.<ext>`. Legacy `.eslintrc.{json,yml,yaml}` are not
+supported in this release — convert them to `.eslintrc.{js,cjs}` first.
+
+Example output for a Node + TypeScript project:
+
+```js
+import { useInsider } from '@useinsider/eslint-config';
+
+export default useInsider({
+    typescriptNode: [
+        {
+            files: ['**/*.{ts,tsx}'],
+            tsconfigPaths: ['tsconfig.json'],
+        },
+    ],
+});
+```
+
+What the CLI installs for that answer set (versions reflect the publish-time
+pins):
+
+- `@useinsider/eslint-config`
+- `eslint`
+- `globals`
+- `typescript`
+- `typescript-eslint`
 
-## Available Presets
+Vue, Jest, or Vitest answers add the matching plugin set (e.g. `eslint-plugin-vue`,
+`vue-eslint-parser`, `eslint-plugin-vue-scoped-css`, `@vue/eslint-config-typescript`,
+`@rushstack/eslint-patch`, `eslint-plugin-jest`, or `@vitest/eslint-plugin`).
 
-We provide a variety of configurations to suit different environments and
-frameworks. Here's a list of available presets:
+## Manual setup
 
-### Vanilla 🍦
+Install the package first:
 
-There are additional presets for DOM (browser) and Node.js environments, beside
-the vanilla configuration. The vanilla is suitable for general JavaScript and
-TypeScript projects that does not have any specific environment and can be
-configured for different environments, such as ServiceWorkers, WebWorkers, etc.
+```bash
+pnpm add -E -D @useinsider/eslint-config
+```
+
+Then create `eslint.config.mjs` and call `useInsider(...)` with the scopes
+your project needs. Each scope holds an array of `{ files, ... }` entries;
+each entry becomes its own flat-config block.
+
+### Node + TypeScript
+
+```js
+import { useInsider } from '@useinsider/eslint-config';
+
+export default useInsider({
+    typescriptNode: [
+        {
+            files: ['**/*.{ts,tsx}'],
+            tsconfigPaths: ['tsconfig.json'],
+        },
+    ],
+    vitest: [
+        { files: ['**/*.{test,spec}.{ts,tsx}'] },
+    ],
+});
+```
+
+### Browser + Vue 3 + TypeScript with split tsconfigs
+
+A project using `tsconfig.app.json` for source and `tsconfig.test.json` for
+tests, with `RouterLink` and `RouterView` as globally-registered components.
 
-| Environment       | Vanilla                                         | Browser (DOM)                                           | Node                                                      |
-| :---------------- | :---------------------------------------------- | :------------------------------------------------------ | :-------------------------------------------------------- |
-| **EcmaScript/JS** | [`javascript`](./src/configs/javascript#readme) | [`javascript-dom`](./src/configs/javascript-dom#readme) | [`javascript-node`](./src/configs/javascript-node#readme) |
-| **TypeScript**    | [`typescript`](./src/configs/typescript#readme) | [`typescript-dom`](./src/configs/typescript-dom#readme) | [`typescript-node`](./src/configs/typescript-node#readme) |
+```js
+import { useInsider } from '@useinsider/eslint-config';
 
-### Library-specific & Standalone Configs
+export default useInsider({
+    vue3Typescript: [
+        {
+            files: ['src/**/*.{ts,tsx,vue}'],
+            tsconfigPaths: ['tsconfig.app.json'],
+            globalComponents: ['RouterLink', 'RouterView'],
+        },
+    ],
+    vitest: [
+        {
+            files: ['**/*.{test,spec}.{ts,tsx}'],
+        },
+    ],
+    typescriptNode: [
+        {
+            files: ['*.config.{ts,mts,cts}'],
+            tsconfigPaths: ['tsconfig.node.json'],
+        },
+    ],
+});
+```
 
-| Environment      | JavaScript & TypeScript                 |
-| :--------------- | :-------------------------------------- |
-| **Config files** | [`config`](./src/configs/config#readme) |
-| **Jest**         | [`jest`](./src/configs/jest#readme)     |
-| **Strict**       | [`strict`](./src/configs/strict#readme) |
+Multiple `tsconfigPaths` entries are supported per block — pass an array of
+paths if a single scope needs more than one project reference.
 
-### Framework-specific
+### Vue 2 + JavaScript with jQuery globals
 
-| Environment                       | JavaScript                                                | TypeScript                                                |
-| :-------------------------------- | :-------------------------------------------------------- | :-------------------------------------------------------- |
-| **Vue 3 (Setup/Composition API)** | [`vue3`](./src/configs/vue3#readme)                       | [`vue3-typescript`](./src/configs/vue3-typescript#readme) |
-| **Vue 2 (Setup/Composition API)** | [`vue2-typescript`](./src/configs/vue2-typescript#readme) | [`vue2-typescript`](./src/configs/vue2-typescript#readme) |
-| **Vue 2 (Options API)**           | [`vue2`](./src/configs/vue2#readme)                       | -                                                         |
+```js
+import { useInsider } from '@useinsider/eslint-config';
+
+export default useInsider({
+    vue2: [
+        { files: ['src/**/*.{js,vue}'] },
+    ],
+    javascriptNode: [
+        { files: ['*.{js,cjs,mjs}'] },
+    ],
+    jquery: [
+        { files: ['src/**/*.{js,vue}'] },
+    ],
+});
+```
 
-### ⏳ Upcoming Configurations
+`jquery` is a top-level scope. Pass an array of `{ files }` entries describing
+the globs that should see the jQuery globals (`$`, `jQuery`). The block is
+emitted after the scope blocks and before `strict`/`spellChecker`, so the
+matching language scope still applies its rule set and jQuery globals are
+layered on top of it.
 
-Planned configurations for the next
+### Strict and spell-checker knobs
 
-- Legacy ES5 💀​
+`strict` and `spellChecker` are flat cross-cutting options. They sit at the
+top level of the config, not inside a scope entry.
+
+```js
+import { useInsider } from '@useinsider/eslint-config';
+
+export default useInsider({
+    typescriptNode: [
+        {
+            files: ['**/*.{ts,tsx}'],
+            tsconfigPaths: ['tsconfig.json'],
+        },
+    ],
+    strict: ['src/**/*.ts'],
+    spellChecker: {
+        ignoredPaths: ['vendor/**', 'dist/**'],
+        customWordListFile: './cspell.custom.json',
+    },
+    silenceRules: ['no-console'],
+});
+```
 
-## Examples
+- `strict: true` applies strict rules to every file.
+- `strict: string[]` applies strict rules only to the matching paths.
+- `spellChecker.customWordListFile` re-points `@cspell/spellchecker` to a
+  project-local word list.
+- `spellChecker.ignoredPaths` turns the spell-checker off for the matching
+  globs (the off block is emitted after the custom-list block, so ignore
+  wins on overlap).
+- `silenceRules` rewrites the severity of the listed rule IDs to `'warn'`
+  across every emitted block while preserving each rule's options.
 
-Checkout the [examples directory](../../examples) to see various apps with the extended ESLint
-configuration.
+## API reference
+
+`useInsider(config)` accepts the following top-level properties. Each scope
+holds an array of entries; each entry produces its own flat-config block.
+
+Every scope entry shape also accepts two common fields:
+
+- `ignores?: string[]` — applies as the block's `ignores` key, scoping the
+  rule set away from the listed globs.
+- `globals?: Record<string, GlobalConf>` — merged on top of the globals the
+  preset already provides; pass `'readonly'`, `'writable'`, or `'off'` per
+  ESLint's `Linter.Globals`. Use this to declare project-specific globals
+  like `APP_URL`, `axios`, `atatus`.
+
+| Property         | Entry shape                                                                                              | Notes |
+| ---------------- | -------------------------------------------------------------------------------------------------------- | ----- |
+| `ignores`        | `string[]` (top-level)                                                                                   | Emits a leading `{ ignores }` block applied to every other block. |
+| `javascript`     | `{ files: string[]; ignores?: string[]; globals?: Linter.Globals }`                                      | Environment-agnostic JS (workers, isomorphic). |
+| `javascriptDom`  | `{ files: string[]; ignores?: string[]; globals?: Linter.Globals }`                                      | Browser JS. |
+| `javascriptNode` | `{ files: string[]; ignores?: string[]; globals?: Linter.Globals }`                                      | Node JS. |
+| `typescript`     | `{ files: string[]; tsconfigPaths: string[]; ignores?: string[]; globals?: Linter.Globals }`             | Environment-agnostic TS. |
+| `typescriptDom`  | `{ files: string[]; tsconfigPaths: string[]; ignores?: string[]; globals?: Linter.Globals }`             | Browser TS. |
+| `typescriptNode` | `{ files: string[]; tsconfigPaths: string[]; ignores?: string[]; globals?: Linter.Globals }`             | Node TS. |
+| `vue2`           | `{ files: string[]; globalComponents?: string[]; ignores?: string[]; globals?: Linter.Globals }`         | Vue 2 single-file components in JS. |
+| `vue3`           | `{ files: string[]; globalComponents?: string[]; ignores?: string[]; globals?: Linter.Globals }`         | Vue 3 single-file components in JS. |
+| `vue2Typescript` | `{ files: string[]; globalComponents?: string[]; tsconfigPaths: string[]; ignores?: string[]; globals?: Linter.Globals }` | Vue 2 + TS. |
+| `vue3Typescript` | `{ files: string[]; globalComponents?: string[]; tsconfigPaths: string[]; ignores?: string[]; globals?: Linter.Globals }` | Vue 3 + TS. |
+| `jest`           | `{ files: string[]; ignores?: string[]; globals?: Linter.Globals }`                                      | Jest test files. |
+| `vitest`         | `{ files: string[]; ignores?: string[]; globals?: Linter.Globals }`                                      | Vitest test files. |
+| `jsdocBasedTs`   | `{ files: string[]; tsconfigPaths: string[]; ignores?: string[]; globals?: Linter.Globals }`             | JS files type-checked via JSDoc. |
+| `jquery`         | `{ files: string[]; ignores?: string[]; globals?: Linter.Globals }`                                      | Layers jQuery globals (`$`, `jQuery`) on top of the matching globs. Per-entry `globals` merge with the jQuery ones rather than replacing them. |
+| `strict`         | `boolean \| string[]`                                                                                    | Applies the strict preset globally (`true`) or scoped to globs. |
+| `spellChecker`   | `{ ignoredPaths?: string[]; customWordListFile?: string }`                                               | Cross-cutting cspell overrides. |
+| `silenceRules`   | `string[]`                                                                                               | Rule IDs to demote to `'warn'` across every block. |
+
+A scope entry with per-entry globals — declare project-specific bindings
+without spreading the `useInsider` return into your own array:
+
+```js
+import { useInsider } from '@useinsider/eslint-config';
+
+export default useInsider({
+    ignores: ['dist', 'coverage'],
+    javascriptDom: [
+        {
+            files: ['src/**/*.js'],
+            ignores: ['src/vendor/**'],
+            globals: {
+                APP_URL: 'readonly',
+                axios: 'readonly',
+                atatus: 'readonly',
+            },
+        },
+    ],
+});
+```
+
+Block-emission order — scope blocks first (in the order their keys were
+inserted into the config object), then `jquery` blocks, then any `strict`
+blocks, then `spellChecker` blocks. Later blocks win on overlap, matching
+ESLint's flat-config precedence model.
+
+`useInsider` returns `Promise<Linter.Config[]>`. Export it directly — ESLint
+9 resolves the Promise at load time. `useInsider`'s return type carries
+through, so no JSDoc annotation is needed; the `UseInsiderResult` type alias
+is exported for TypeScript callers that wrap `useInsider` in a helper of
+their own.
+
+`silenceRules()` (named export) is also available as a global registration
+hook. Call it at module top level to register rule IDs to demote *before*
+`useInsider` is invoked; the per-call `silenceRules: [...]` option layers
+on top.
+
+```js
+import { useInsider, silenceRules } from '@useinsider/eslint-config';
+
+silenceRules(['no-magic-numbers']);
+
+export default useInsider({ /* ... */ });
+```
+
+## Migrating from v1.x
+
+v2 is a hard break. The summary:
+
+- **`preset: string[]`** → top-level scope properties. The order in the
+  v1 `preset` array no longer matters — the new shape has one property per
+  scope and overrides are explicit.
+
+  ```diff
+  - await useInsider({
+  -     preset: ['typescript-node'],
+  -     config: { files: ['src/**/*.ts'], languageOptions: { parserOptions: { project: ['./tsconfig.json'] } } },
+  - })
+  + useInsider({
+  +     typescriptNode: [
+  +         { files: ['src/**/*.ts'], tsconfigPaths: ['tsconfig.json'] },
+  +     ],
+  + })
+  ```
+
+- **`preset: ['vue3-typescript']` + `config`** → `vue3Typescript` entry
+  with a dedicated `globalComponents` field. No more hand-rolled
+  `vue/no-undef-components` overrides.
+
+  ```diff
+  - await useInsider({
+  -     preset: ['vue3-typescript'],
+  -     config: {
+  -         files: ['src/**/*.{ts,vue}'],
+  -         languageOptions: { parserOptions: { project: ['./tsconfig.app.json'] } },
+  -         rules: { 'vue/no-undef-components': ['error', { ignorePatterns: ['^RouterLink$', '^RouterView$'] }] },
+  -     },
+  - })
+  + useInsider({
+  +     vue3Typescript: [
+  +         {
+  +             files: ['src/**/*.{ts,vue}'],
+  +             tsconfigPaths: ['tsconfig.app.json'],
+  +             globalComponents: ['RouterLink', 'RouterView'],
+  +         },
+  +     ],
+  + })
+  ```
+
+- **`preset: ['strict']`** → top-level `strict: true | string[]`.
+
+  ```diff
+  - await useInsider({ preset: ['typescript-node', 'strict'], config: { files: ['src/**/*.ts'] } })
+  + useInsider({
+  +     typescriptNode: [{ files: ['src/**/*.ts'], tsconfigPaths: ['tsconfig.json'] }],
+  +     strict: true,
+  + })
+  ```
+
+  Behavior change: in v1 the `strict` preset was always global when listed.
+  In v2, `strict: true` keeps that global behavior; `strict: string[]`
+  scopes the strict rule set to the matching globs only. If you have
+  paths-targeted strict checks, set `strict: [...]` instead of
+  `strict: true`.
+
+- **Shape change**: `useInsider(...)` is now exported directly as the
+  default export, without `await`, without spread, and without an array
+  wrap. ESLint 9 resolves the Promise on load. The old pattern
+  `export default [...await useInsider({...})]` still parses, but the
+  preferred shape is `export default useInsider({...})`. There is no
+  supported override path — describe every glob you want linted inside
+  the call, including jQuery files via the dedicated `jquery` scope.
+
+- **Removed**: the `preset` array, the `config: Linter.Config` escape
+  hatch, and the `config` preset itself. Configuration-file linting is
+  now an ordinary `typescriptNode` (or `javascriptNode`) entry pointed at
+  the right tsconfig.
+
+- **Kept**: `silenceRules` accepts the same `string[]` shape both as a
+  top-level option and via the named `silenceRules()` export.
+  `silenceDependencyWarning()` works unchanged. Side-effect lines such as
+  `silenceDependencyWarning(true)` continue to sit above the
+  `export default useInsider({...})` call.
+
+## First lint after install
+
+The first time you run lint after installing v2, `ensureDependencies` may
+detect that your project's `eslint` or `globals` version is older than the
+pin and auto-install them, exiting with code `1`. Run lint again and it
+will complete normally.
 
 ## Troubleshooting
 
 ### `Missing dependencies detected:`
-If you see this error, it means that the configuration you are trying to use
-has some dependencies that are not installed in your project. You can install
-them by running the command that it provides.
 
-If you want to silence the warning, you can add the following code to your
-ESLint config file.
+If you see this error, your project is missing a peer plugin this config
+needs. The error message lists the install command. To silence the warning
+permanently:
 
 ```js
 import { useInsider, silenceDependencyWarning } from '@useinsider/eslint-config';
 
 silenceDependencyWarning(['@cspell/eslint-plugin', '@stylistic/eslint-plugin']);
-```
 
-Or you can pass `true` to the `silenceDependencyWarning` function to silence all
-warnings.
+export default useInsider({ /* ... */ });
+```
 
-However, this is not recommended as it may cause unexpected issues while
-maintaining the dependencies.
+Passing `true` silences every warning; that is not recommended because the
+warning is the only signal that your installed plugin versions drifted
+from what the config expects.
 
 ```js
-import { useInsider, silenceDependencyWarning } from '@useinsider/eslint-config';
-
 silenceDependencyWarning(true);
 ```
 
 ## Contributing
 
-Please refer to the [CONTRIBUTING.md](CONTRIBUTING.md) file for guidelines on
-how to contribute to this project.
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) at the repo root.

package/dist/builders/jquery.d.ts

@@ -0,0 +1,5 @@
+import type { Linter } from 'eslint';
+export interface JqueryEntry {
+    files: string[];
+}
+export declare function buildJqueryBlocks(entries: readonly JqueryEntry[] | undefined): Linter.Config[];

package/dist/builders/scopeBlocks.d.ts

@@ -0,0 +1,40 @@
+import type { Linter } from 'eslint';
+export interface JsEntry {
+    files: string[];
+}
+export interface TsEntry {
+    files: string[];
+    tsconfigPaths: string[];
+}
+export interface VueEntry {
+    files: string[];
+    globalComponents?: string[];
+}
+export interface VueTsEntry {
+    files: string[];
+    globalComponents?: string[];
+    tsconfigPaths: string[];
+}
+export interface TestEntry {
+    files: string[];
+}
+export type ScopeEntry = JsEntry | TsEntry | VueEntry | VueTsEntry | TestEntry;
+declare const scopeMap: {
+    javascript(): Promise<typeof import("../configs/javascript")>;
+    javascriptDom(): Promise<typeof import("../configs/javascript-dom")>;
+    javascriptNode(): Promise<typeof import("../configs/javascript-node")>;
+    typescript(): Promise<typeof import("../configs/typescript")>;
+    typescriptDom(): Promise<typeof import("../configs/typescript-dom")>;
+    typescriptNode(): Promise<typeof import("../configs/typescript-node")>;
+    vue2(): Promise<typeof import("../configs/vue2")>;
+    vue3(): Promise<typeof import("../configs/vue3")>;
+    vue2Typescript(): Promise<typeof import("../configs/vue2-typescript")>;
+    vue3Typescript(): Promise<typeof import("../configs/vue3-typescript")>;
+    jest(): Promise<typeof import("../configs/jest")>;
+    vitest(): Promise<typeof import("../configs/vitest")>;
+    jsdocBasedTs(): Promise<typeof import("../configs/jsdoc-based-ts")>;
+};
+export type ScopeName = keyof typeof scopeMap;
+export declare function isScopeName(key: string): key is ScopeName;
+export declare function buildScopeBlocks(scope: ScopeName, entries: readonly ScopeEntry[]): Promise<Linter.Config[]>;
+export {};

package/dist/builders/spellChecker.d.ts

@@ -0,0 +1,7 @@
+import type { Linter } from 'eslint';
+interface SpellCheckerInput {
+    ignoredPaths?: string[];
+    customWordListFile?: string;
+}
+export declare function buildSpellCheckerBlocks(input: SpellCheckerInput | undefined): Linter.Config[];
+export {};

package/dist/builders/strict.d.ts

@@ -0,0 +1,2 @@
+import type { Linter } from 'eslint';
+export declare function buildStrictBlocks(value: boolean | string[] | undefined): Promise<Linter.Config[]>;

package/dist/builders/typescript.d.ts

@@ -0,0 +1,6 @@
+import type { Linter } from 'eslint';
+interface TypescriptOverrideInput {
+    tsconfigPaths: string[];
+}
+export declare function applyTypescriptOverrides<BlockType extends Linter.Config>(block: BlockType, input: TypescriptOverrideInput): BlockType;
+export {};

package/dist/builders/vue.d.ts

@@ -0,0 +1,8 @@
+import type { Linter } from 'eslint';
+interface VueOverrideInput {
+    globalComponents?: string[];
+}
+export declare function escapeRegex(input: string): string;
+export declare function anchoredEscapeRegex(input: string): string;
+export declare function applyVueOverrides<BlockType extends Linter.Config>(block: BlockType, input: VueOverrideInput): BlockType;
+export {};