eslint-plugin-ts-type-forge 0.2.0

package/dist/rules/prefer-non-empty-array.mjs

@@ -0,0 +1,81 @@
+import { getNonEmptyArrayElementText } from './ast-utils.mjs';
+import { NON_EMPTY_ARRAY_TYPE_NAME, TS_TYPE_FORGE_MODULE } from './constants.mjs';
+import { getImportedLocalName, getTsTypeForgeImports, hasConflictingDeclaration, buildTypeImportFix } from './import-utils.mjs';
+
+const DEFAULT_IMPORT_STYLE = "global";
+const preferNonEmptyArray = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Replace the `readonly [V, ...V[]]` tuple spelling with `NonEmptyArray<V>` from ts-type-forge."
+    },
+    fixable: "code",
+    schema: [
+      {
+        type: "object",
+        properties: {
+          importStyle: {
+            type: "string",
+            enum: ["global", "named"],
+            description: [
+              "How `NonEmptyArray` is brought into scope.",
+              "'global' (default) assumes the ambient globals of",
+              "`ts-type-forge/global` and never touches imports;",
+              "'named' makes the autofix add",
+              `\`import { type ${NON_EMPTY_ARRAY_TYPE_NAME} } from '${TS_TYPE_FORGE_MODULE}';\``,
+              "when the name is not imported yet."
+            ].join(" ")
+          }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      useNonEmptyArray: "Replace `{{original}}` with `{{replacement}}` from ts-type-forge."
+    }
+  },
+  create: (context) => {
+    const sourceCode = context.sourceCode;
+    const program = sourceCode.ast;
+    const importStyle = context.options[0]?.importStyle ?? DEFAULT_IMPORT_STYLE;
+    const importedLocalName = getImportedLocalName(
+      getTsTypeForgeImports(program),
+      NON_EMPTY_ARRAY_TYPE_NAME
+    );
+    const mut_nodesToFix = [];
+    return {
+      TSTypeOperator: (node) => {
+        const elementText = getNonEmptyArrayElementText(node, sourceCode);
+        if (elementText === void 0) return;
+        mut_nodesToFix.push({ node, elementText });
+      },
+      "Program:exit": () => {
+        if (mut_nodesToFix.length === 0) return;
+        if (importedLocalName === void 0 && hasConflictingDeclaration(program, NON_EMPTY_ARRAY_TYPE_NAME)) {
+          return;
+        }
+        const localName = importedLocalName ?? NON_EMPTY_ARRAY_TYPE_NAME;
+        const needsImport = importStyle === "named" && importedLocalName === void 0;
+        for (const [index, { node, elementText }] of mut_nodesToFix.entries()) {
+          const replacement = `${localName}<${elementText}>`;
+          context.report({
+            node,
+            messageId: "useNonEmptyArray",
+            data: {
+              original: sourceCode.getText(node),
+              replacement
+            },
+            fix: (fixer) => [
+              ...index === 0 && needsImport ? buildTypeImportFix(fixer, program, NON_EMPTY_ARRAY_TYPE_NAME) : [],
+              fixer.replaceText(node, replacement)
+            ]
+          });
+        }
+      }
+    };
+  },
+  defaultOptions: [{ importStyle: DEFAULT_IMPORT_STYLE }]
+};
+
+export { preferNonEmptyArray };
+//# sourceMappingURL=prefer-non-empty-array.mjs.map

package/dist/rules/prefer-non-empty-array.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefer-non-empty-array.mjs","sources":["../../src/rules/prefer-non-empty-array.mts"],"sourcesContent":["import { type TSESLint, type TSESTree } from '@typescript-eslint/utils';\nimport { getNonEmptyArrayElementText } from './ast-utils.mjs';\nimport {\n  NON_EMPTY_ARRAY_TYPE_NAME,\n  TS_TYPE_FORGE_MODULE,\n} from './constants.mjs';\nimport {\n  buildTypeImportFix,\n  getImportedLocalName,\n  getTsTypeForgeImports,\n  hasConflictingDeclaration,\n} from './import-utils.mjs';\n\ntype ImportStyle = 'global' | 'named';\n\ntype Options = readonly [\n  Readonly<{\n    importStyle?: ImportStyle;\n  }>?,\n];\n\ntype MessageIds = 'useNonEmptyArray';\n\nconst DEFAULT_IMPORT_STYLE: ImportStyle = 'global';\n\nexport const preferNonEmptyArray: TSESLint.RuleModule<MessageIds, Options> = {\n  meta: {\n    type: 'suggestion',\n    docs: {\n      description:\n        'Replace the `readonly [V, ...V[]]` tuple spelling with `NonEmptyArray<V>` from ts-type-forge.',\n    },\n    fixable: 'code',\n    schema: [\n      {\n        type: 'object',\n        properties: {\n          importStyle: {\n            type: 'string',\n            enum: ['global', 'named'],\n            description: [\n              'How `NonEmptyArray` is brought into scope.',\n              \"'global' (default) assumes the ambient globals of\",\n              '`ts-type-forge/global` and never touches imports;',\n              \"'named' makes the autofix add\",\n              `\\`import { type ${NON_EMPTY_ARRAY_TYPE_NAME} } from '${TS_TYPE_FORGE_MODULE}';\\``,\n              'when the name is not imported yet.',\n            ].join(' '),\n          },\n        },\n        additionalProperties: false,\n      },\n    ],\n    messages: {\n      useNonEmptyArray:\n        'Replace `{{original}}` with `{{replacement}}` from ts-type-forge.',\n    },\n  },\n\n  create: (context) => {\n    const sourceCode = context.sourceCode;\n\n    const program = sourceCode.ast;\n\n    // `context.options` is what the user actually configured; `defaultOptions`\n    // is only merged in by `RuleCreator`, which plain rule objects do not use.\n    const importStyle = context.options[0]?.importStyle ?? DEFAULT_IMPORT_STYLE;\n\n    const importedLocalName = getImportedLocalName(\n      getTsTypeForgeImports(program),\n      NON_EMPTY_ARRAY_TYPE_NAME,\n    );\n\n    const mut_nodesToFix: {\n      node: TSESTree.TSTypeOperator;\n      elementText: string;\n    }[] = [];\n\n    return {\n      TSTypeOperator: (node) => {\n        const elementText = getNonEmptyArrayElementText(node, sourceCode);\n\n        if (elementText === undefined) return;\n\n        mut_nodesToFix.push({ node, elementText });\n      },\n      'Program:exit': () => {\n        if (mut_nodesToFix.length === 0) return;\n\n        // Rewriting to `NonEmptyArray<...>` is only sound when that name is\n        // free (or already bound to the ts-type-forge export). Otherwise the\n        // rewritten type would resolve to the wrong declaration — most\n        // notably inside ts-type-forge's own sources, which define\n        // `NonEmptyArray`.\n        if (\n          importedLocalName === undefined &&\n          hasConflictingDeclaration(program, NON_EMPTY_ARRAY_TYPE_NAME)\n        ) {\n          return;\n        }\n\n        const localName = importedLocalName ?? NON_EMPTY_ARRAY_TYPE_NAME;\n\n        const needsImport =\n          importStyle === 'named' && importedLocalName === undefined;\n\n        for (const [index, { node, elementText }] of mut_nodesToFix.entries()) {\n          const replacement = `${localName}<${elementText}>`;\n\n          context.report({\n            node,\n            messageId: 'useNonEmptyArray',\n            data: {\n              original: sourceCode.getText(node),\n              replacement,\n            },\n            fix: (fixer) => [\n              ...(index === 0 && needsImport\n                ? buildTypeImportFix(fixer, program, NON_EMPTY_ARRAY_TYPE_NAME)\n                : []),\n              fixer.replaceText(node, replacement),\n            ],\n          });\n        }\n      },\n    };\n  },\n  defaultOptions: [{ importStyle: DEFAULT_IMPORT_STYLE }],\n} as const;\n"],"names":[],"mappings":"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"}

package/dist/rules/rules.d.mts

@@ -0,0 +1,6 @@
+export declare const tsTypeForgeRules: {
+    readonly 'prefer-non-empty-array': import("@typescript-eslint/utils/ts-eslint").RuleModule<"useNonEmptyArray", readonly [(Readonly<{
+        importStyle?: "global" | "named";
+    }> | undefined)?], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener>;
+};
+//# sourceMappingURL=rules.d.mts.map

package/dist/rules/rules.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.mts","sourceRoot":"","sources":["../../src/rules/rules.mts"],"names":[],"mappings":"AAGA,eAAO,MAAM,gBAAgB;;;;CAEa,CAAC"}

package/dist/rules/rules.mjs

@@ -0,0 +1,8 @@
+import { preferNonEmptyArray } from './prefer-non-empty-array.mjs';
+
+const tsTypeForgeRules = {
+  "prefer-non-empty-array": preferNonEmptyArray
+};
+
+export { tsTypeForgeRules };
+//# sourceMappingURL=rules.mjs.map

package/dist/rules/rules.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.mjs","sources":["../../src/rules/rules.mts"],"sourcesContent":["import { type ESLintPlugin } from '../types.mjs';\nimport { preferNonEmptyArray } from './prefer-non-empty-array.mjs';\n\nexport const tsTypeForgeRules = {\n  'prefer-non-empty-array': preferNonEmptyArray,\n} as const satisfies ESLintPlugin['rules'];\n"],"names":[],"mappings":";;AAGO,MAAM,gBAAA,GAAmB;AAAA,EAC9B,wBAAA,EAA0B;AAC5B;;;;"}

package/dist/types.d.mts

@@ -0,0 +1,4 @@
+import { type TSESLint } from '@typescript-eslint/utils';
+import { type DeepReadonly } from 'ts-type-forge';
+export type ESLintPlugin = DeepReadonly<TSESLint.FlatConfig.Plugin>;
+//# sourceMappingURL=types.d.mts.map

package/dist/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","sourceRoot":"","sources":["../src/types.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,MAAM,MAAM,YAAY,GAAG,YAAY,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC"}

package/dist/types.mjs

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=types.mjs.map

package/dist/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "eslint-plugin-ts-type-forge",
+  "version": "0.2.0",
+  "private": false,
+  "description": "ESLint rules that steer type declarations toward ts-type-forge idioms.",
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "ts-type-forge",
+    "typescript",
+    "types"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noshiro-pf/ts-type-forge.git",
+    "directory": "packages/eslint-plugin-ts-type-forge"
+  },
+  "license": "Apache-2.0",
+  "author": "noshiro-pf <noshiro.pf@gmail.com>",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsx ./scripts/cmd/build.mts",
+    "build:min": "tsx ./scripts/cmd/build.mts --skip-check",
+    "check:ext": "tsx ./scripts/cmd/check-ext.mts",
+    "fmt": "format-uncommitted --cwd .",
+    "fmt:diff": "format-diff-from origin/main --cwd .",
+    "fmt:full": "pnpm run z:prettier .",
+    "gen:rule-types": "tsx ./scripts/cmd/gen-rule-types.mts",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "pnpm run z:vitest run",
+    "test:cov": "pnpm run z:vitest run --coverage",
+    "testw": "pnpm run z:vitest",
+    "tsc": "node ../../node_modules/typescript-native/bin/tsc --noEmit",
+    "tscw": "node ../../node_modules/typescript-native/bin/tsc --noEmit --watch -p ./tsconfig.json",
+    "type-check": "node ../../node_modules/typescript-native/bin/tsc --noEmit",
+    "z:prettier": "prettier --config ../../.prettierrc --ignore-path ../../.prettierignore --ignore-path ../../.gitignore --ignore-unknown --no-error-on-unmatched-pattern --write",
+    "z:vitest": "vitest --config ./configs/vitest.config.mts"
+  },
+  "dependencies": {
+    "@typescript-eslint/utils": "8.65.0",
+    "ts-type-forge": "workspace:*"
+  },
+  "devDependencies": {
+    "@typescript-eslint/parser": "8.65.0",
+    "@typescript-eslint/rule-tester": "8.65.0",
+    "dedent": "1.7.2"
+  },
+  "peerDependencies": {
+    "eslint": ">=9.0.0",
+    "typescript": ">=5.0.0"
+  },
+  "engines": {
+    "node": ">=22.22.2",
+    "pnpm": ">=9.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/src/index.mts

@@ -0,0 +1,7 @@
+export { eslintPluginTsTypeForge } from './plugin.mjs';
+export type {
+  EslintTsTypeForgeRules,
+  EslintTsTypeForgeRulesOption,
+} from './rule-types.mjs';
+export { tsTypeForgeRules } from './rules/index.mjs';
+export { type ESLintPlugin } from './types.mjs';

package/src/plugin.mts

@@ -0,0 +1,9 @@
+import { tsTypeForgeRules } from './rules/index.mjs';
+import { type ESLintPlugin } from './types.mjs';
+
+export const eslintPluginTsTypeForge: ESLintPlugin = {
+  meta: {
+    name: 'eslint-plugin-ts-type-forge',
+  },
+  rules: tsTypeForgeRules,
+} as const;

package/src/rule-types.mts

@@ -0,0 +1,89 @@
+/* cSpell:disable */
+
+// This file is auto-generated by `pnpm run gen:rule-types`
+// (`scripts/cmd/gen-rule-types.mts`). Do not edit it manually.
+
+import { type TSESLint } from '@typescript-eslint/utils';
+import { type Linter } from 'eslint';
+import { type TypeEq } from 'ts-type-forge';
+import { type tsTypeForgeRules } from './rules/index.mjs';
+
+type SpreadOptionsIfIsArray<
+  T extends readonly [Linter.StringSeverity, unknown],
+> = T[1] extends readonly unknown[]
+  ? readonly [Linter.StringSeverity, ...T[1]]
+  : T;
+
+/**
+ * Extracts the options tuple type of a rule from its TypeScript
+ * implementation, so that option types stay in sync with the rule source
+ * without converting `meta.schema` (JSON Schema) back into TypeScript types.
+ */
+type RuleOptionsOf<Name extends keyof typeof tsTypeForgeRules> =
+  (typeof tsTypeForgeRules)[Name] extends TSESLint.RuleModule<
+    infer _MessageIds extends string,
+    infer Options extends readonly unknown[]
+  >
+    ? Options
+    : never;
+
+/**
+ * @description Replace the `readonly [V, ...V[]]` tuple spelling with `NonEmptyArray<V>` from ts-type-forge.
+ *
+ *  ```md
+ *  | key        | value      |
+ *  | :--------- | :--------- |
+ *  | type       | suggestion |
+ *  | deprecated | false      |
+ *  | fixable    | code       |
+ *  ```
+ */
+namespace PreferNonEmptyArray {
+  /**
+   * ### schema
+   *
+   * ```json
+   * [
+   *   {
+   *     "type": "object",
+   *     "properties": {
+   *       "importStyle": {
+   *         "type": "string",
+   *         "enum": [
+   *           "global",
+   *           "named"
+   *         ],
+   *         "description": "How `NonEmptyArray` is brought into scope. 'global' (default) assumes the ambient globals of `ts-type-forge/global` and never touches imports; 'named' makes the autofix add `import { type NonEmptyArray } from 'ts-type-forge';` when the name is not imported yet."
+   *       }
+   *     },
+   *     "additionalProperties": false
+   *   }
+   * ]
+   * ```
+   */
+  export type Options = NonNullable<RuleOptionsOf<'prefer-non-empty-array'>[0]>;
+
+  export type RuleEntry =
+    | 'off'
+    | Linter.Severity
+    | SpreadOptionsIfIsArray<readonly [Linter.StringSeverity, Options]>;
+}
+
+export type EslintTsTypeForgeRules = Readonly<{
+  'ts-type-forge/prefer-non-empty-array': PreferNonEmptyArray.RuleEntry;
+}>;
+
+export type EslintTsTypeForgeRulesOption = Readonly<{
+  'ts-type-forge/prefer-non-empty-array': PreferNonEmptyArray.Options;
+}>;
+
+// If this assertion fails to type-check, this generated file has drifted from
+// the actual plugin rules — re-run `pnpm run gen:rule-types`.
+type AssertTrue<B extends true> = B;
+
+export type RuleNamesAreInSync = AssertTrue<
+  TypeEq<
+    keyof EslintTsTypeForgeRules,
+    `ts-type-forge/${keyof typeof tsTypeForgeRules}`
+  >
+>;

package/src/rules/ast-utils.mts

@@ -0,0 +1,76 @@
+import {
+  AST_NODE_TYPES,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types */
+
+/**
+ * Matches the "non-empty array" tuple spelling — `readonly [V, ...V[]]` (and
+ * its equivalent `readonly [V, ...(readonly V[])]`) — and returns the source
+ * text of `V`, or `undefined` when `node` is not that shape.
+ *
+ * Deliberately narrow:
+ *
+ * - Only the `readonly` operator is matched. A mutable `[V, ...V[]]` is a
+ *   different type (`MutableNonEmptyArray<V>`) and is left alone.
+ * - Exactly two elements, the second being a rest element whose element type is
+ *   textually identical to the first.
+ * - Labelled members (`readonly [head: V, ...tail: V[]]`) are skipped, since
+ *   rewriting them would silently drop the labels.
+ */
+export const getNonEmptyArrayElementText = (
+  node: TSESTree.TSTypeOperator,
+  sourceCode: TSESLint.SourceCode,
+): string | undefined => {
+  if (node.operator !== 'readonly') return undefined;
+
+  const tuple = node.typeAnnotation;
+
+  if (tuple?.type !== AST_NODE_TYPES.TSTupleType) return undefined;
+
+  const [head, tail, ...rest] = tuple.elementTypes;
+
+  if (head === undefined || tail === undefined || rest.length > 0) {
+    return undefined;
+  }
+
+  if (
+    head.type === AST_NODE_TYPES.TSRestType ||
+    head.type === AST_NODE_TYPES.TSOptionalType ||
+    head.type === AST_NODE_TYPES.TSNamedTupleMember ||
+    tail.type !== AST_NODE_TYPES.TSRestType
+  ) {
+    return undefined;
+  }
+
+  const restElementType = getArrayElementType(tail.typeAnnotation);
+
+  if (restElementType === undefined) return undefined;
+
+  const headText = sourceCode.getText(head);
+
+  return normalizeWhitespace(headText) ===
+    normalizeWhitespace(sourceCode.getText(restElementType))
+    ? headText
+    : undefined;
+};
+
+/** Unwraps `V[]` and `readonly V[]` to `V`. */
+const getArrayElementType = (
+  node: TSESTree.TypeNode,
+): TSESTree.TypeNode | undefined => {
+  if (node.type === AST_NODE_TYPES.TSArrayType) return node.elementType;
+
+  return node.type === AST_NODE_TYPES.TSTypeOperator &&
+    node.operator === 'readonly' &&
+    node.typeAnnotation?.type === AST_NODE_TYPES.TSArrayType
+    ? node.typeAnnotation.elementType
+    : undefined;
+};
+
+const normalizeWhitespace = (text: string): string =>
+  text.replaceAll(/\s+/gu, ' ').trim();
+
+/* eslint-enable @typescript-eslint/prefer-readonly-parameter-types */

package/src/rules/constants.mts

@@ -0,0 +1,3 @@
+export const TS_TYPE_FORGE_MODULE = 'ts-type-forge';
+
+export const NON_EMPTY_ARRAY_TYPE_NAME = 'NonEmptyArray';

package/src/rules/import-utils.mts

@@ -0,0 +1,105 @@
+import {
+  AST_NODE_TYPES,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+import { TS_TYPE_FORGE_MODULE } from './constants.mjs';
+
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types */
+
+/** Every `import ... from 'ts-type-forge'` declaration in the file. */
+export const getTsTypeForgeImports = (
+  program: TSESTree.Program,
+): readonly TSESTree.ImportDeclaration[] =>
+  program.body.filter(
+    (node): node is TSESTree.ImportDeclaration =>
+      node.type === AST_NODE_TYPES.ImportDeclaration &&
+      node.source.value === TS_TYPE_FORGE_MODULE,
+  );
+
+/**
+ * Returns the in-scope local name a given ts-type-forge export is imported as
+ * (handling aliases such as `import type { NonEmptyArray as NEA }` → `'NEA'`),
+ * or `undefined` when it is not imported. Used so autofixes reference the
+ * binding that actually exists rather than the canonical name.
+ */
+export const getImportedLocalName = (
+  importDeclarations: readonly TSESTree.ImportDeclaration[],
+  importedName: string,
+): string | undefined =>
+  importDeclarations
+    .flatMap((declaration) => declaration.specifiers)
+    .find(
+      (specifier) =>
+        specifier.type === AST_NODE_TYPES.ImportSpecifier &&
+        (specifier.imported.type === AST_NODE_TYPES.Identifier
+          ? specifier.imported.name
+          : specifier.imported.value) === importedName,
+    )?.local.name;
+
+/**
+ * Whether the file already binds `name` to something that is not the
+ * ts-type-forge export of the same name — a local type alias / interface /
+ * class / enum, or an import from another module. Autofixes that introduce
+ * `name` must bail out in that case, because the rewritten type would resolve
+ * to the wrong declaration. (ts-type-forge's own sources, which declare
+ * `NonEmptyArray` themselves, are the motivating example.)
+ */
+export const hasConflictingDeclaration = (
+  program: TSESTree.Program,
+  name: string,
+): boolean =>
+  program.body.some((node) => {
+    if (node.type === AST_NODE_TYPES.ImportDeclaration) {
+      return (
+        node.source.value !== TS_TYPE_FORGE_MODULE &&
+        node.specifiers.some((specifier) => specifier.local.name === name)
+      );
+    }
+
+    return declaresName(
+      node.type === AST_NODE_TYPES.ExportNamedDeclaration ||
+        node.type === AST_NODE_TYPES.ExportDefaultDeclaration
+        ? node.declaration
+        : node,
+      name,
+    );
+  });
+
+/**
+ * Inserts `import { type <name> } from 'ts-type-forge';` at the top of the
+ * file. Placement is deliberately naive: prettier-plugin-organize-imports (or
+ * any equivalent) merges and sorts it afterwards.
+ */
+export const buildTypeImportFix = (
+  fixer: TSESLint.RuleFixer,
+  program: TSESTree.Program,
+  name: string,
+): readonly TSESLint.RuleFix[] =>
+  [
+    fixer.insertTextBefore(
+      program,
+      `import { type ${name} } from '${TS_TYPE_FORGE_MODULE}';\n`,
+    ),
+  ] as const;
+
+const declaresName = (
+  node: TSESTree.Node | null | undefined,
+  name: string,
+): boolean => {
+  if (node === null || node === undefined) return false;
+
+  if (
+    node.type === AST_NODE_TYPES.TSTypeAliasDeclaration ||
+    node.type === AST_NODE_TYPES.TSInterfaceDeclaration ||
+    node.type === AST_NODE_TYPES.TSEnumDeclaration
+  ) {
+    return node.id.name === name;
+  }
+
+  return (
+    node.type === AST_NODE_TYPES.ClassDeclaration && node.id?.name === name
+  );
+};
+
+/* eslint-enable @typescript-eslint/prefer-readonly-parameter-types */

package/src/rules/index.mts

@@ -0,0 +1 @@
+export * from './rules.mjs';

package/src/rules/prefer-non-empty-array.mts

@@ -0,0 +1,129 @@
+import { type TSESLint, type TSESTree } from '@typescript-eslint/utils';
+import { getNonEmptyArrayElementText } from './ast-utils.mjs';
+import {
+  NON_EMPTY_ARRAY_TYPE_NAME,
+  TS_TYPE_FORGE_MODULE,
+} from './constants.mjs';
+import {
+  buildTypeImportFix,
+  getImportedLocalName,
+  getTsTypeForgeImports,
+  hasConflictingDeclaration,
+} from './import-utils.mjs';
+
+type ImportStyle = 'global' | 'named';
+
+type Options = readonly [
+  Readonly<{
+    importStyle?: ImportStyle;
+  }>?,
+];
+
+type MessageIds = 'useNonEmptyArray';
+
+const DEFAULT_IMPORT_STYLE: ImportStyle = 'global';
+
+export const preferNonEmptyArray: TSESLint.RuleModule<MessageIds, Options> = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Replace the `readonly [V, ...V[]]` tuple spelling with `NonEmptyArray<V>` from ts-type-forge.',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          importStyle: {
+            type: 'string',
+            enum: ['global', 'named'],
+            description: [
+              'How `NonEmptyArray` is brought into scope.',
+              "'global' (default) assumes the ambient globals of",
+              '`ts-type-forge/global` and never touches imports;',
+              "'named' makes the autofix add",
+              `\`import { type ${NON_EMPTY_ARRAY_TYPE_NAME} } from '${TS_TYPE_FORGE_MODULE}';\``,
+              'when the name is not imported yet.',
+            ].join(' '),
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      useNonEmptyArray:
+        'Replace `{{original}}` with `{{replacement}}` from ts-type-forge.',
+    },
+  },
+
+  create: (context) => {
+    const sourceCode = context.sourceCode;
+
+    const program = sourceCode.ast;
+
+    // `context.options` is what the user actually configured; `defaultOptions`
+    // is only merged in by `RuleCreator`, which plain rule objects do not use.
+    const importStyle = context.options[0]?.importStyle ?? DEFAULT_IMPORT_STYLE;
+
+    const importedLocalName = getImportedLocalName(
+      getTsTypeForgeImports(program),
+      NON_EMPTY_ARRAY_TYPE_NAME,
+    );
+
+    const mut_nodesToFix: {
+      node: TSESTree.TSTypeOperator;
+      elementText: string;
+    }[] = [];
+
+    return {
+      TSTypeOperator: (node) => {
+        const elementText = getNonEmptyArrayElementText(node, sourceCode);
+
+        if (elementText === undefined) return;
+
+        mut_nodesToFix.push({ node, elementText });
+      },
+      'Program:exit': () => {
+        if (mut_nodesToFix.length === 0) return;
+
+        // Rewriting to `NonEmptyArray<...>` is only sound when that name is
+        // free (or already bound to the ts-type-forge export). Otherwise the
+        // rewritten type would resolve to the wrong declaration — most
+        // notably inside ts-type-forge's own sources, which define
+        // `NonEmptyArray`.
+        if (
+          importedLocalName === undefined &&
+          hasConflictingDeclaration(program, NON_EMPTY_ARRAY_TYPE_NAME)
+        ) {
+          return;
+        }
+
+        const localName = importedLocalName ?? NON_EMPTY_ARRAY_TYPE_NAME;
+
+        const needsImport =
+          importStyle === 'named' && importedLocalName === undefined;
+
+        for (const [index, { node, elementText }] of mut_nodesToFix.entries()) {
+          const replacement = `${localName}<${elementText}>`;
+
+          context.report({
+            node,
+            messageId: 'useNonEmptyArray',
+            data: {
+              original: sourceCode.getText(node),
+              replacement,
+            },
+            fix: (fixer) => [
+              ...(index === 0 && needsImport
+                ? buildTypeImportFix(fixer, program, NON_EMPTY_ARRAY_TYPE_NAME)
+                : []),
+              fixer.replaceText(node, replacement),
+            ],
+          });
+        }
+      },
+    };
+  },
+  defaultOptions: [{ importStyle: DEFAULT_IMPORT_STYLE }],
+} as const;