@aneuhold/eslint-config 2.0.5 → 3.0.0

package/README.md

@@ -4,12 +4,12 @@ Personal ESLint Configuration
 
 ## Notes on Architecture
 
-- TypeScript was specifically avoided in this library because it was complicating the build step. It might work in this repo, but it kept causing issues in consuming repos. JS by itself seems to work great.
+- This library is authored in **raw TypeScript with no build step**. The configs and rule source ship as `.ts`, and each consumer's ESLint transpiles them on the fly via [jiti](https://github.com/unjs/jiti).
 - All dependencies should be able to be only defined in this repo outside of ESLint and Prettier, as those will be brought in to consuming repos as peer deps.
 - In order for there not to be crossover between configuration dependencies, each config should be brought in as the full path to the configuration. For example:
 
-```js
-import tsLibConfig from '@aneuhold/eslint-config/src/ts-lib-config.js';
+```ts
+import tsLibConfig from '@aneuhold/eslint-config/src/configs/ts-lib-config';
 ```
 
 ## Usage
@@ -45,66 +45,27 @@ Make sure to add the following settings to VSCode settings.json:
 
 Then add a prettier file, such as the one in this repo [here](.prettierrc.js).
 
-### Setup for `CommonJS`
+The config sources are `.ts`, so add an `eslint.config.ts` that spreads in the
+config for your stack. ESLint transpiles both your config and the package's
+sources on the fly via jiti — no build step.
 
-Add `eslint.config.js` like so:
+```ts
+import tsLibConfig from '@aneuhold/eslint-config/src/configs/ts-lib-config';
 
-```js
-const config = (async () => (await import('./eslint.config.mjs')).default)();
-
-module.exports = config;
-```
-
-Add `eslint.config.mjs` like so:
-
-```js
-// @ts-check
-
-import tsLibConfig from '@aneuhold/eslint-config/src/ts-lib-config.js';
-
-/** @type {import('@typescript-eslint/utils').TSESLint.FlatConfig.ConfigArray} */
 export default [
   ...tsLibConfig,
   {
-    // other override settings. e.g. for `files: ['**/*.test.*']`
-  },
-];
-```
-
-### Setup for `ESNext` (ES Modules)
-
-Add `eslint.config.js` like so:
-
-```js
-// @ts-check
-
-import svelteConfig from '@aneuhold/eslint-config/src/svelte-config.js';
-
-/** @type {import('@typescript-eslint/utils').TSESLint.FlatConfig.ConfigArray} */
-export default [
-  ...svelteConfig,
-  {
-    // other override settings. e.g. for `files: ['**/*.test.*']`
+    // your overrides, e.g. for `files: ['**/*.test.*']`
   },
 ];
 ```
 
-### Setup for Monorepo
-
-If you have specific configs for different folders, make sure to exclude those folders in the top-level config! For example:
+Swap `ts-lib-config` for whichever config matches the project: `svelte-config`,
+`react-config`, `react-next-config`, or `angular-config`.
 
-```js
-import tsLibConfig from '@aneuhold/eslint-config/src/ts-lib-config.js';
+**Monorepo:** if nested folders have their own configs, add an `ignores` entry
+so the top-level config doesn't also lint them:
 
-/** @type {import('@typescript-eslint/utils').TSESLint.FlatConfig.ConfigArray} */
-export default [
-  ...tsLibConfig,
-  {
-    // other override settings. e.g. for `files: ['**/*.test.*']`
-    rules: {},
-  },
-  {
-    ignores: ['**/lib', 'svelte', 'react'],
-  },
-];
+```ts
+{ ignores: ['**/lib', 'svelte', 'react'] }
 ```

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@aneuhold/eslint-config",
-  "version": "2.0.5",
+  "version": "3.0.0",
   "description": "Main ESLint Configuration for personal projects",
-  "main": "./src/ts-lib-config.js",
+  "main": "./src/configs/ts-lib-config.ts",
   "packageManager": "pnpm@10.33.0",
   "scripts": {
-    "dev": "nodemon -e js --exec \"local-npm publish\"",
+    "dev": "nodemon -e ts --exec \"local-npm publish\"",
     "unpub": "local-npm unpublish",
     "pushpub": "pnpm version patch && git push",
     "upgrade:all": "pnpm update --latest",
-    "lint": "pnpm eslint"
+    "check": "tsc --noEmit",
+    "lint": "pnpm eslint",
+    "test": "vitest run"
   },
   "type": "module",
   "repository": {
@@ -36,32 +38,36 @@
   },
   "dependencies": {
     "@eslint/js": "^10.0.1",
-    "@next/eslint-plugin-next": "^16.2.4",
+    "@next/eslint-plugin-next": "^16.2.7",
     "@stylistic/eslint-plugin-js": "^4.4.1",
     "@stylistic/eslint-plugin-ts": "^4.4.1",
-    "@typescript-eslint/eslint-plugin": "^8.59.0",
-    "@typescript-eslint/parser": "^8.59.0",
-    "angular-eslint": "^21.3.1",
+    "@typescript-eslint/eslint-plugin": "^8.60.1",
+    "@typescript-eslint/parser": "^8.60.1",
+    "@typescript-eslint/utils": "^8.60.1",
+    "angular-eslint": "^21.4.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-jsdoc": "^62.9.0",
+    "eslint-plugin-jsdoc": "^63.0.1",
     "eslint-plugin-prefer-arrow": "^1.2.3",
-    "eslint-plugin-prettier": "^5.5.5",
+    "eslint-plugin-prettier": "^5.5.6",
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-react-refresh": "^0.5.2",
     "eslint-plugin-simple-import-sort": "^13.0.0",
-    "eslint-plugin-svelte": "^3.17.0",
+    "eslint-plugin-svelte": "^3.19.0",
     "eslint-plugin-unused-imports": "^4.4.1",
-    "globals": "^17.5.0",
-    "prettier-plugin-svelte": "^3.5.1",
-    "typescript-eslint": "^8.59.0"
+    "globals": "^17.6.0",
+    "prettier-plugin-svelte": "^4.1.0",
+    "typescript-eslint": "^8.60.1"
   },
   "devDependencies": {
-    "@aneuhold/local-npm-registry": "^0.2.30",
-    "@types/node": "^25.6.0",
-    "eslint": "^10.2.1",
+    "@aneuhold/local-npm-registry": "^0.2.32",
+    "@types/node": "^25.9.1",
+    "@typescript-eslint/rule-tester": "^8.60.1",
+    "eslint": "^10.4.1",
+    "jiti": "^2.7.0",
     "prettier": "^3.8.3",
-    "svelte": "^5.50.0",
-    "typescript": "^6.0.3"
+    "svelte": "^5.56.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.4"
   }
 }

package/src/{react-next-config.js → configs/react-next-config.ts}

@@ -1,15 +1,16 @@
 import nextPlugin from '@next/eslint-plugin-next';
 import { defineConfig } from 'eslint/config';
-import reactConfig from './react-config.js';
-
-// Ya, this is kind of weird, but if you dig into the actual code in the next plugin, this is correct.
-const { flatConfig } = nextPlugin;
+import reactConfig from './react-config';
 
 export default defineConfig(
   ...reactConfig,
   {
     files: ['**/*.{js,jsx,ts,tsx}'],
-    extends: [flatConfig.recommended],
+    // @next/eslint-plugin-next is not typed, so `flatConfig` resolves as an
+    // unresolvable type.
+    // @ts-expect-error - `flatConfig` exists at runtime but isn't in the plugin's types.
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    extends: [nextPlugin.flatConfig.recommended],
     rules: {
       // Allow export names that are used by Next.js in the app directory.
       'react-refresh/only-export-components': [

package/src/{svelte-config.js → configs/svelte-config.ts}

@@ -6,6 +6,7 @@ import eslintPluginSvelte from 'eslint-plugin-svelte';
 import { defineConfig } from 'eslint/config';
 import globals from 'globals';
 import tseslint from 'typescript-eslint';
+import { aneuholdRules } from '../rules';
 
 // Shared extraFileExtensions constant to avoid project service reloads.
 // See: https://typescript-eslint.io/troubleshooting/typed-linting/performance/#changes-to-extrafileextensions-with-projectservice
@@ -21,6 +22,7 @@ export default defineConfig(
       ...tseslint.configs.strictTypeChecked,
       jsdoc.configs['flat/recommended-typescript'],
       eslintPluginPrettierRecommended,
+      aneuholdRules,
     ],
     plugins: {
       'simple-import-sort': simpleImportSort,
@@ -143,9 +145,7 @@ export default defineConfig(
   //    eslint-plugin-svelte's flat/recommended already includes base config
   //    which sets up svelte-eslint-parser and the svelte processor.
   //    flat/prettier disables svelte rules that conflict with Prettier.
-  // @ts-expect-error - eslint-plugin-svelte is not typed
   ...eslintPluginSvelte.configs['flat/recommended'],
-  // @ts-expect-error - eslint-plugin-svelte is not typed
   ...eslintPluginSvelte.configs['flat/prettier'],
 
   // 4. TypeScript integration for Svelte files: tell svelte-eslint-parser

package/src/{ts-lib-config.js → configs/ts-lib-config.ts}

@@ -4,8 +4,9 @@ import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended'
 import { defineConfig } from 'eslint/config';
 import globals from 'globals';
 import tseslint from 'typescript-eslint';
+import { aneuholdRules } from '../rules';
 
-const defaultConfig = defineConfig(
+export default defineConfig(
   {
     files: ['**/*.js', '**/*.mjs', '**/*.ts'],
     extends: [
@@ -13,6 +14,7 @@ const defaultConfig = defineConfig(
       ...tseslint.configs.strictTypeChecked,
       jsdoc.configs['flat/recommended-typescript'],
       eslintPluginPrettierRecommended,
+      aneuholdRules,
     ],
     languageOptions: {
       parser: tseslint.parser,
@@ -70,15 +72,8 @@ const defaultConfig = defineConfig(
     // disable type-aware linting on JS files
     files: ['**/*.js', '**/*.mjs'],
     extends: [tseslint.configs.disableTypeChecked],
-  }
-);
-
-export default defineConfig(
-  ...defaultConfig,
-  {
-    // other override settings. e.g. for `files: ['**/*.test.*']`
   },
   {
     ignores: ['.yarn', 'build', 'lib', 'node_modules', 'eslint.config.js', '**/.DS_Store'],
-  } // overrides global ignores
+  }
 );

package/src/rules/index.ts

@@ -0,0 +1,45 @@
+import { type Linter } from 'eslint';
+import { noPrivateModifier } from './no-private-modifier/no-private-modifier';
+import { serviceFileStructure } from './service-file-structure/service-file-structure';
+
+/**
+ * The runtime `aneuhold` plugin object.
+ */
+const aneuholdPlugin = {
+  meta: { name: 'aneuhold' },
+  rules: {
+    'no-private-modifier': noPrivateModifier,
+    'service-file-structure': serviceFileStructure,
+  },
+};
+
+/**
+ * The same plugin object handed out through a deliberately narrow type that
+ * hides `rules`. This is what lets the fragment below be accepted by
+ * `defineConfig`: ESLint core's strict `RuleDefinition` type would otherwise
+ * reject rules built with typescript-eslint's `RuleCreator` (whose looser
+ * `RuleModule` type isn't assignable — typescript-eslint#10396 / eslint#19155).
+ * By erasing `rules` from the public type, core never type-checks them, while
+ * the runtime object still registers them normally.
+ *
+ * This mirrors how typescript-eslint widens its own public `plugin`/`configs`
+ * types to satisfy both `defineConfig()` and `tseslint.config()`:
+ * https://github.com/typescript-eslint/typescript-eslint/blob/v8.60.1/packages/typescript-eslint/src/compatibility-types.ts
+ */
+const compatiblePlugin: { meta: { name: string } } = aneuholdPlugin;
+
+/**
+ * Flat-config fragment that registers the `aneuhold` plugin and enables its
+ * rules. Drop it into a config block's `extends` array (or spread it into a
+ * standalone config object); either way it inherits the host block's `files`
+ * scope.
+ */
+export const aneuholdRules: Linter.Config = {
+  plugins: {
+    aneuhold: compatiblePlugin,
+  },
+  rules: {
+    'aneuhold/no-private-modifier': 'error',
+    'aneuhold/service-file-structure': 'error',
+  },
+};

package/src/rules/no-private-modifier/buildClassFixes.ts

@@ -0,0 +1,39 @@
+import { type TSESLint } from '@typescript-eslint/utils';
+import { type FixTarget } from './types';
+
+/**
+ * Builds every edit needed to convert a class's fixable members in one go:
+ * dropping each `private` modifier, prefixing each name with `#`, and prefixing
+ * each rewritable reference with `#`. Bundling the whole class into one fix lets
+ * it convert in a single pass even when a member's references sit past another
+ * member being converted.
+ *
+ * @param fixer The ESLint fixer
+ * @param sourceCode The source code object
+ * @param targets The members to convert, with their references
+ */
+export const buildClassFixes = (
+  fixer: TSESLint.RuleFixer,
+  sourceCode: Readonly<TSESLint.SourceCode>,
+  targets: FixTarget[]
+): TSESLint.RuleFix[] => {
+  const fixes: TSESLint.RuleFix[] = [];
+
+  for (const { member, refs } of targets) {
+    const privateToken = sourceCode.getTokens(member).find((token) => token.value === 'private');
+    const afterPrivate = privateToken && sourceCode.getTokenAfter(privateToken);
+    if (privateToken && afterPrivate) {
+      fixes.push(fixer.removeRange([privateToken.range[0], afterPrivate.range[0]]));
+    }
+
+    fixes.push(fixer.insertTextBefore(member.key, '#'));
+    for (const ref of refs) {
+      fixes.push(fixer.insertTextBefore(ref.property, '#'));
+    }
+  }
+
+  // ESLint merges a report's edits by range and requires them ordered and
+  // non-overlapping.
+  fixes.sort((a, b) => a.range[0] - b.range[0]);
+  return fixes;
+};

package/src/rules/no-private-modifier/classFrame.ts

@@ -0,0 +1,143 @@
+import { AST_NODE_TYPES, type TSESTree } from '@typescript-eslint/utils';
+import { type ClassFrame, type ClassNode } from './types';
+
+/**
+ * Creates a fresh frame for a class, scanning its members up-front for the
+ * private names eligible to convert and the `#names` already in use.
+ *
+ * @param classNode The class declaration or expression
+ */
+export const createClassFrame = (classNode: ClassNode): ClassFrame => {
+  const candidateNames = new Set<string>();
+  const existingPrivateNames = new Set<string>();
+
+  for (const member of classNode.body.body) {
+    if (
+      member.type !== AST_NODE_TYPES.PropertyDefinition &&
+      member.type !== AST_NODE_TYPES.MethodDefinition &&
+      member.type !== AST_NODE_TYPES.AccessorProperty
+    ) {
+      continue;
+    }
+    if (member.key.type === AST_NODE_TYPES.PrivateIdentifier) {
+      existingPrivateNames.add(member.key.name);
+    } else if (
+      !member.computed &&
+      member.key.type === AST_NODE_TYPES.Identifier &&
+      member.accessibility === 'private'
+    ) {
+      candidateNames.add(member.key.name);
+    }
+  }
+
+  return {
+    classNode,
+    className: classNode.id?.name ?? null,
+    candidateNames,
+    existingPrivateNames,
+    thisRefs: new Map(),
+    staticRefs: new Map(),
+    blocked: new Set(),
+    rebindDepth: 0,
+  };
+};
+
+/**
+ * Records a member access against the frame, bucketing it as a rewritable
+ * `this.name` / `ClassName.name` reference or blocking the name when the access
+ * has no safe `#` equivalent.
+ *
+ * @param frame The enclosing class's frame
+ * @param node The member-access expression
+ * @param thisIsInstance Whether `this` here refers to the class instance/itself
+ */
+export const classifyMemberAccess = (
+  frame: ClassFrame,
+  node: TSESTree.MemberExpression,
+  thisIsInstance: boolean
+): void => {
+  const { property, object } = node;
+
+  if (node.computed) {
+    if (
+      property.type === AST_NODE_TYPES.Literal &&
+      typeof property.value === 'string' &&
+      frame.candidateNames.has(property.value)
+    ) {
+      frame.blocked.add(property.value);
+    }
+    return;
+  }
+
+  if (property.type !== AST_NODE_TYPES.Identifier || !frame.candidateNames.has(property.name)) {
+    return;
+  }
+  const name = property.name;
+
+  if (node.optional) {
+    frame.blocked.add(name);
+    return;
+  }
+
+  if (object.type === AST_NODE_TYPES.ThisExpression) {
+    // A `this` that has rebound (inside a nested non-arrow function) isn't our
+    // member, so it's neither rewritten nor a problem — just ignored.
+    if (thisIsInstance) {
+      addReference(frame.thisRefs, name, node);
+    }
+    return;
+  }
+
+  if (
+    object.type === AST_NODE_TYPES.Identifier &&
+    frame.className !== null &&
+    object.name === frame.className
+  ) {
+    addReference(frame.staticRefs, name, node);
+    return;
+  }
+
+  // Access on some other object: without type information this could be a
+  // same-class instance (which `#` allows) or an unrelated property. Can't
+  // tell, so refuse to autofix this name.
+  frame.blocked.add(name);
+};
+
+/**
+ * Blocks any candidate name destructured off an object (`const { name } = …`),
+ * since destructuring has no `#name` form.
+ *
+ * @param frame The enclosing class's frame
+ * @param node The object pattern
+ */
+export const recordDestructuring = (frame: ClassFrame, node: TSESTree.ObjectPattern): void => {
+  for (const property of node.properties) {
+    if (
+      property.type === AST_NODE_TYPES.Property &&
+      property.key.type === AST_NODE_TYPES.Identifier &&
+      frame.candidateNames.has(property.key.name)
+    ) {
+      frame.blocked.add(property.key.name);
+    }
+  }
+};
+
+/**
+ * Appends a reference to the per-name list in `map`.
+ *
+ * @param map The reference map to add to
+ * @param name The member name
+ * @param node The member-access expression
+ */
+const addReference = (
+  map: Map<string, TSESTree.MemberExpression[]>,
+  name: string,
+  node: TSESTree.MemberExpression
+): void => {
+  const existing = map.get(name);
+  if (existing) {
+    existing.push(node);
+  } else {
+    map.set(name, [node]);
+  }
+};

package/src/rules/no-private-modifier/classReports.ts

@@ -0,0 +1,57 @@
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+import { type ClassFrame, type FixableMember, type FixTarget, type MessageId } from './types';
+
+/** A member to report, with the message describing why. */
+export type MemberReport = { member: FixableMember; messageId: MessageId };
+
+/** The outcome of analyzing a class: what to report, and what an autofix converts. */
+export type ClassReports = { reports: MemberReport[]; targets: FixTarget[] };
+
+/**
+ * Turns a fully-populated frame into the per-member reports and the set of
+ * fixable conversion targets. Each name claims its references once, so a
+ * get/set pair sharing a name doesn't rewrite the same reference twice.
+ *
+ * @param frame The class frame, after traversal has recorded its references
+ */
+export const collectClassReports = (frame: ClassFrame): ClassReports => {
+  const reports: MemberReport[] = [];
+  const targets: FixTarget[] = [];
+  const claimedNames = new Set<string>();
+
+  for (const member of frame.classNode.body.body) {
+    if (
+      member.type !== AST_NODE_TYPES.PropertyDefinition &&
+      member.type !== AST_NODE_TYPES.MethodDefinition &&
+      member.type !== AST_NODE_TYPES.AccessorProperty
+    ) {
+      continue;
+    }
+    if (member.accessibility !== 'private') {
+      continue;
+    }
+
+    if (member.type === AST_NODE_TYPES.MethodDefinition && member.kind === 'constructor') {
+      reports.push({ member, messageId: 'privateConstructor' });
+      continue;
+    }
+
+    const messageId: MessageId =
+      member.type === AST_NODE_TYPES.MethodDefinition ? 'privateMethod' : 'privateField';
+    reports.push({ member, messageId });
+
+    const name =
+      !member.computed && member.key.type === AST_NODE_TYPES.Identifier ? member.key.name : null;
+    if (name === null || frame.blocked.has(name) || frame.existingPrivateNames.has(name)) {
+      continue;
+    }
+
+    const refs = claimedNames.has(name)
+      ? []
+      : [...(frame.thisRefs.get(name) ?? []), ...(frame.staticRefs.get(name) ?? [])];
+    claimedNames.add(name);
+    targets.push({ member, refs });
+  }
+
+  return { reports, targets };
+};

package/src/rules/no-private-modifier/no-private-modifier.md

@@ -0,0 +1,72 @@
+# `no-private-modifier`
+
+Class members must use the ECMAScript `#private` syntax instead of the
+TypeScript `private` accessibility modifier.
+
+Native `#private` fields are enforced at runtime and are truly inaccessible from
+outside the class, whereas TypeScript's `private` is a compile-time-only
+annotation that disappears in the emitted JavaScript. Standardizing on `#`
+removes that ambiguity.
+
+## What it checks
+
+Every form of the `private` modifier on a class member is reported:
+
+- Instance and `static` fields, including `accessor` properties.
+- Instance and `static` methods, getters, and setters.
+- Constructors (`private constructor() {}`).
+
+`public` and `protected` members, and members with no modifier, are left alone —
+this rule is only concerned with replacing `private`.
+
+**Constructor parameter properties are allowed.** `constructor(private foo: T)`
+is a concise, readable shorthand that declares and assigns the field in one
+place, and `#private` has no equivalent. Flagging it would force the verbose
+field-plus-assignment form for no real benefit, so the rule permits it.
+
+## Autofix
+
+None. Converting `private` to `#` requires renaming every reference
+(`this.foo` → `this.#foo`), and parameter properties additionally need a field
+declaration plus a constructor-body assignment. These transforms are not safe to
+apply automatically, so violations are reported without a fix.
+
+## Rule details
+
+Examples of **incorrect** code:
+
+```ts
+class Counter {
+  private count = 0;
+  private static total = 0;
+  private accessor label = '';
+
+  private increment(): void {}
+
+  private constructor() {}
+}
+```
+
+Examples of **correct** code:
+
+```ts
+class Counter {
+  #count = 0;
+  static #total = 0;
+  accessor #label = '';
+
+  #increment(): void {}
+}
+
+class Service {
+  // Parameter properties are allowed.
+  constructor(private readonly client: Client) {}
+}
+```
+
+## When not to use it
+
+Disable it if you need TypeScript `private` semantics specifically — for
+example, when a member must remain reflectively accessible at runtime, or when
+interoperating with code that reaches into instances in ways true `#private`
+fields would break.