@aneuhold/eslint-config 2.0.4 → 3.0.0

package/src/rules/service-file-structure/serviceModel.ts

@@ -0,0 +1,134 @@
+import { AST_NODE_TYPES, type TSESLint, type TSESTree } from '@typescript-eslint/utils';
+import type { ServiceMessageId } from './messages';
+
+/**
+ * The rule context, narrowed to this rule's message ids and (empty) options, so
+ * every validation module gets fully-typed `context.report` calls.
+ */
+export type ServiceRuleContext = Readonly<TSESLint.RuleContext<ServiceMessageId, []>>;
+
+/**
+ * The shared model the orchestrator builds once and hands to every validation:
+ * the file's single service class plus the derived names and program body the
+ * validations operate on.
+ */
+export type ServiceModel = {
+  body: TSESTree.ProgramStatement[];
+  /** The class declaration itself. */
+  classNode: TSESTree.ClassDeclaration;
+  /** The statement carrying the class — itself, or its `export` wrapper. */
+  outer: TSESTree.ProgramStatement;
+  className: string;
+  /** Conventional singleton instance name: the class name, first letter lowercased. */
+  instance: string;
+};
+
+/**
+ * A validation step: inspects the shared model and reports any violations.
+ */
+export type ServiceValidation = (context: ServiceRuleContext, model: ServiceModel) => void;
+
+/**
+ * A file-level validation step that depends only on the file itself (e.g. its
+ * name), so it runs even when there is no resolvable service class.
+ */
+export type ServiceFileValidation = (context: ServiceRuleContext) => void;
+
+/**
+ * Describes a top-level `const x = new SomeClass()` binding: whether it is the
+ * exempt singleton for this service, plus the bound name and declarator for
+ * follow-up checks.
+ */
+export type SingletonInfo = {
+  isSingleton: boolean;
+  name?: string;
+  declarator?: TSESTree.LetOrConstOrVarDeclarator;
+};
+
+/**
+ * Derives the conventional singleton instance name from a class name by
+ * lowercasing the first character (e.g. `WakeLockService` -> `wakeLockService`).
+ *
+ * @param className The service class name
+ */
+export const instanceNameFor = (className: string): string =>
+  `${className.charAt(0).toLowerCase()}${className.slice(1)}`;
+
+/**
+ * Inspects a top-level variable declaration and reports whether it is the one
+ * exempt singleton binding `const <name> = new <className>()`.
+ *
+ * @param node The variable declaration statement
+ * @param className The file's single service class name
+ */
+export const singletonInfo = (
+  node: TSESTree.VariableDeclaration,
+  className: string
+): SingletonInfo => {
+  if (node.kind !== 'const' || node.declarations.length !== 1) {
+    return { isSingleton: false };
+  }
+  const [declarator] = node.declarations;
+  const isSingleton =
+    declarator.id.type === AST_NODE_TYPES.Identifier &&
+    declarator.init?.type === AST_NODE_TYPES.NewExpression &&
+    declarator.init.callee.type === AST_NODE_TYPES.Identifier &&
+    declarator.init.callee.name === className;
+  if (!isSingleton || declarator.id.type !== AST_NODE_TYPES.Identifier) {
+    return { isSingleton: false };
+  }
+  return { isSingleton: true, name: declarator.id.name, declarator };
+};
+
+/**
+ * Collects the file's top-level classes (bare or exported) and, if there is
+ * exactly one named class, returns the shared model. Otherwise reports the
+ * blocking class-shape problem and returns `null` so no further validation runs.
+ *
+ * @param context The rule context
+ * @param program The program node
+ */
+export const resolveServiceClass = (
+  context: ServiceRuleContext,
+  program: TSESTree.Program
+): ServiceModel | null => {
+  const classes: { node: TSESTree.ClassDeclaration; outer: TSESTree.ProgramStatement }[] = [];
+  for (const statement of program.body) {
+    if (statement.type === AST_NODE_TYPES.ClassDeclaration) {
+      classes.push({ node: statement, outer: statement });
+    } else if (
+      (statement.type === AST_NODE_TYPES.ExportNamedDeclaration ||
+        statement.type === AST_NODE_TYPES.ExportDefaultDeclaration) &&
+      statement.declaration?.type === AST_NODE_TYPES.ClassDeclaration
+    ) {
+      classes.push({ node: statement.declaration, outer: statement });
+    }
+  }
+
+  if (classes.length === 0) {
+    context.report({ node: program, messageId: 'classRequired' });
+    return null;
+  }
+
+  if (classes.length > 1) {
+    for (const extra of classes.slice(1)) {
+      context.report({ node: extra.node, messageId: 'singleClassOnly' });
+    }
+    return null;
+  }
+
+  const { node: classNode, outer } = classes[0];
+  const className = classNode.id?.name;
+  if (!className) {
+    context.report({ node: classNode, messageId: 'classMustBeNamed' });
+    return null;
+  }
+
+  return {
+    body: program.body,
+    classNode,
+    outer,
+    className,
+    instance: instanceNameFor(className),
+  };
+};

package/src/rules/service-file-structure/validations/validateDefaultExportIsConstBound.ts

@@ -0,0 +1,40 @@
+import { AST_NODE_TYPES, type TSESTree } from '@typescript-eslint/utils';
+import type { ServiceValidation } from '../serviceModel';
+
+/**
+ * Flags an inline `export default new XService();` and rewrites it to the
+ * `const`-bound singleton form. Exporting the class itself as the default
+ * (`export default class XService {}` or `export default XService`) is left
+ * alone, since such a class may be intended for extension.
+ *
+ * @param context The rule context
+ * @param model The shared service model
+ */
+export const validateDefaultExportIsConstBound: ServiceValidation = (context, model) => {
+  const defaultExport = model.body.find(
+    (statement): statement is TSESTree.ExportDefaultDeclaration =>
+      statement.type === AST_NODE_TYPES.ExportDefaultDeclaration
+  );
+
+  const decl = defaultExport?.declaration;
+  const isInlineInstance =
+    decl?.type === AST_NODE_TYPES.NewExpression &&
+    decl.callee.type === AST_NODE_TYPES.Identifier &&
+    decl.callee.name === model.className;
+
+  if (!defaultExport || !isInlineInstance) {
+    return;
+  }
+
+  const { instance, className } = model;
+  context.report({
+    node: defaultExport,
+    messageId: 'trailingInstanceExport',
+    data: { instance, className },
+    fix: (fixer) =>
+      fixer.replaceText(
+        defaultExport,
+        `const ${instance} = ${context.sourceCode.getText(decl)};\nexport default ${instance};`
+      ),
+  });
+};

package/src/rules/service-file-structure/validations/validateFileNamingConvention.ts

@@ -0,0 +1,18 @@
+import { usesServiceFileNaming } from '../isServiceFile';
+import type { ServiceFileValidation } from '../serviceModel';
+
+/**
+ * Requires an in-scope service file to follow the `<Name>.service.ts` /
+ * `<Name>.service.svelte.ts` naming convention, where `<Name>` is PascalCase
+ * (starts with a capital letter). Reported at the top of the file since the
+ * violation is the file name itself, not any particular node.
+ *
+ * @param context The rule context
+ */
+export const validateFileNamingConvention: ServiceFileValidation = (context) => {
+  if (usesServiceFileNaming(context.filename)) {
+    return;
+  }
+
+  context.report({ loc: { line: 1, column: 0 }, messageId: 'fileNaming' });
+};

package/src/rules/service-file-structure/validations/validateNoTopLevelFunctions.ts

@@ -0,0 +1,23 @@
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+import type { ServiceValidation } from '../serviceModel';
+
+/**
+ * Forbids functions declared at the top level of a service file, whether bare
+ * (`function f() {}`) or exported (`export function f() {}`). Behavior belongs
+ * inside the class as a (private) method.
+ *
+ * @param context The rule context
+ * @param model The shared service model
+ */
+export const validateNoTopLevelFunctions: ServiceValidation = (context, model) => {
+  for (const statement of model.body) {
+    if (statement.type === AST_NODE_TYPES.FunctionDeclaration) {
+      context.report({ node: statement, messageId: 'noTopLevelFunction' });
+    } else if (
+      statement.type === AST_NODE_TYPES.ExportNamedDeclaration &&
+      statement.declaration?.type === AST_NODE_TYPES.FunctionDeclaration
+    ) {
+      context.report({ node: statement, messageId: 'noTopLevelFunction' });
+    }
+  }
+};

package/src/rules/service-file-structure/validations/validateNoTopLevelVariables.ts

@@ -0,0 +1,33 @@
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+import { type ServiceValidation, singletonInfo } from '../serviceModel';
+
+/**
+ * Forbids variables declared at the top level of a service file — both exported
+ * named declarations (`export const x = ...`) and bare ones. Constants belong
+ * inside the class as private instance or static fields. The sole exception is
+ * the singleton binding `const xService = new XService();`, whose name is
+ * validated separately.
+ *
+ * @param context The rule context
+ * @param model The shared service model
+ */
+export const validateNoTopLevelVariables: ServiceValidation = (context, model) => {
+  const data = { instance: model.instance, className: model.className };
+
+  for (const statement of model.body) {
+    if (
+      statement.type === AST_NODE_TYPES.ExportNamedDeclaration &&
+      statement.declaration?.type === AST_NODE_TYPES.VariableDeclaration
+    ) {
+      context.report({ node: statement, messageId: 'noTopLevelVariable', data });
+      continue;
+    }
+
+    if (
+      statement.type === AST_NODE_TYPES.VariableDeclaration &&
+      !singletonInfo(statement, model.className).isSingleton
+    ) {
+      context.report({ node: statement, messageId: 'noTopLevelVariable', data });
+    }
+  }
+};

package/src/rules/service-file-structure/validations/validateSingletonName.ts

@@ -0,0 +1,26 @@
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+import { type ServiceValidation, singletonInfo } from '../serviceModel';
+
+/**
+ * Requires the singleton binding `const <name> = new <ClassName>()` to use the
+ * conventional instance name — the class name with a lowercased first letter.
+ *
+ * @param context The rule context
+ * @param model The shared service model
+ */
+export const validateSingletonName: ServiceValidation = (context, model) => {
+  for (const statement of model.body) {
+    if (statement.type !== AST_NODE_TYPES.VariableDeclaration) {
+      continue;
+    }
+
+    const info = singletonInfo(statement, model.className);
+    if (info.isSingleton && info.name !== model.instance) {
+      context.report({
+        node: info.declarator ?? statement,
+        messageId: 'instanceName',
+        data: { expected: model.instance, className: model.className, actual: info.name ?? '' },
+      });
+    }
+  }
+};

package/src/utils/createRule.ts

@@ -0,0 +1,12 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+
+const REPO_URL = 'https://github.com/aneuhold/eslint-config';
+
+/**
+ * Shared `RuleCreator` for this package's custom ESLint rules. Each rule's
+ * documentation URL points at the rule's own markdown file, which lives next to
+ * its implementation at `src/rules/<rule-name>/<rule-name>.md`.
+ */
+export const createRule = ESLintUtils.RuleCreator(
+  (name) => `${REPO_URL}/blob/main/src/rules/${name}/${name}.md`
+);

package/src/utils/eslintTestSetup.ts

@@ -0,0 +1,19 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { afterAll, describe, it } from 'vitest';
+
+/**
+ * Wires `@typescript-eslint/rule-tester`'s `RuleTester` up to Vitest's test
+ * hooks. `RuleTester` calls `describe`/`it`/`afterAll` to register its
+ * generated cases, but it only reads them off its own static properties — and
+ * Vitest does not expose these as globals unless `globals: true` is set. So
+ * they have to be assigned explicitly before any `RuleTester` is constructed.
+ *
+ * See the "Vitest" section of the rule-tester docs:
+ * https://typescript-eslint.io/packages/rule-tester/#vitest
+ */
+export const setupEslintRuleTester = (): void => {
+  RuleTester.afterAll = afterAll;
+  RuleTester.describe = describe;
+  RuleTester.it = it;
+  RuleTester.itOnly = it.only;
+};