eslint-plugin-ts-type-forge 0.7.3 → 0.8.1

package/dist/rules/std-type-rule-utils.mjs

@@ -1,37 +1,54 @@
-import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES, } from '@typescript-eslint/utils';
 import { Arr } from 'ts-data-forge';
 import { isLocallyBound } from './ast-utils.mjs';
 import { resolveTypeName } from './import-style.mjs';
 import { buildTypeImportFix } from './import-utils.mjs';
 
-const reportStdTypeReference = (context, node, alternatives, messageIds, importStyle) => {
-  const typeName = node.typeName;
-  if (typeName.type !== AST_NODE_TYPES.Identifier) return;
-  const stdName = typeName.name;
-  const candidates = alternatives.get(stdName);
-  if (candidates === void 0) return;
-  if (isLocallyBound(context.sourceCode, node, stdName)) return;
-  const program = context.sourceCode.ast;
-  context.report({
-    node: typeName,
-    messageId: messageIds.report,
-    data: { name: stdName, alternatives: formatAlternatives(candidates) },
-    suggest: candidates.flatMap((candidate) => {
-      const target = resolveTypeName(program, candidate, importStyle);
-      return target === void 0 ? [] : [
-        {
-          messageId: messageIds.suggestion,
-          data: { name: stdName, replacement: target.localName },
-          fix: (fixer) => Arr.toPushed(
-            target.needsImport ? buildTypeImportFix(fixer, program, candidate) : [],
-            fixer.replaceText(typeName, target.localName)
-          )
-        }
-      ];
-    })
-  });
+
+
+
+
+
+
+
+
+
+export const reportStdTypeReference = (context, node, alternatives, messageIds, importStyle) => {
+    const typeName = node.typeName;
+
+    if (typeName.type !== AST_NODE_TYPES.Identifier)
+        return;
+    const stdName = typeName.name;
+    const candidates = alternatives.get(stdName);
+    if (candidates === undefined)
+        return;
+
+
+    if (isLocallyBound(context.sourceCode, node, stdName))
+        return;
+    const program = context.sourceCode.ast;
+    context.report({
+        node: typeName,
+        messageId: messageIds.report,
+        data: { name: stdName, alternatives: formatAlternatives(candidates) },
+        suggest: candidates.flatMap((candidate) => {
+            const target = resolveTypeName(program, candidate, importStyle);
+
+
+            return target === undefined
+                ? []
+                : [
+                    {
+                        messageId: messageIds.suggestion,
+                        data: { name: stdName, replacement: target.localName },
+                        fix: (fixer) => Arr.toPushed(target.needsImport
+                            ? buildTypeImportFix(fixer, program, candidate)
+                            : [], fixer.replaceText(typeName, target.localName)),
+                    },
+                ];
+        }),
+    });
 };
-const formatAlternatives = (candidates) => candidates.map((candidate) => `\`${candidate}\``).join(" or ");
 
-export { reportStdTypeReference };
-//# sourceMappingURL=std-type-rule-utils.mjs.map
+const formatAlternatives = (candidates) => candidates.map((candidate) => `\`${candidate}\``).join(' or ');
+//# sourceMappingURL=std-type-rule-utils.mjs.map

package/dist/rules/std-type-rule-utils.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"std-type-rule-utils.mjs","sources":["../../src/rules/std-type-rule-utils.mts"],"sourcesContent":["import {\n  AST_NODE_TYPES,\n  type TSESLint,\n  type TSESTree,\n} from '@typescript-eslint/utils';\nimport { Arr } from 'ts-data-forge';\nimport { isLocallyBound } from './ast-utils.mjs';\nimport { resolveTypeName, type ImportStyle } from './import-style.mjs';\nimport { buildTypeImportFix } from './import-utils.mjs';\n\n/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types */\n\n/**\n * The ts-type-forge replacements offered for one standard-library type, in the\n * order they are suggested.\n */\nexport type StdTypeAlternatives = ReadonlyMap<string, readonly string[]>;\n\n/**\n * Reports a reference to a banned standard-library type and offers one\n * suggestion per ts-type-forge alternative.\n *\n * Choosing between the alternatives is a semantic decision — `StrictExclude`\n * additionally checks that the subtrahend is part of the union, `ReadonlyRecord`\n * and `MutableRecord` describe different types — so this is deliberately *not*\n * an autofix. Each suggestion carries its own import fix, which is safe because\n * ESLint applies suggestions one at a time.\n */\nexport const reportStdTypeReference = <MessageIds extends string>(\n  context: TSESLint.RuleContext<MessageIds, readonly unknown[]>,\n  node: TSESTree.TSTypeReference,\n  alternatives: StdTypeAlternatives,\n  messageIds: Readonly<{ report: MessageIds; suggestion: MessageIds }>,\n  importStyle: ImportStyle,\n): void => {\n  const typeName = node.typeName;\n\n  // `ns.Pick` / `import('…').Pick` never denote the standard-library type.\n  if (typeName.type !== AST_NODE_TYPES.Identifier) return;\n\n  const stdName = typeName.name;\n\n  const candidates = alternatives.get(stdName);\n\n  if (candidates === undefined) return;\n\n  // A file that declares — or imports — its own `Pick` does not mean the\n  // standard-library one, so there is nothing to steer.\n  if (isLocallyBound(context.sourceCode, node, stdName)) return;\n\n  const program = context.sourceCode.ast;\n\n  context.report({\n    node: typeName,\n    messageId: messageIds.report,\n    data: { name: stdName, alternatives: formatAlternatives(candidates) },\n    suggest: candidates.flatMap((candidate) => {\n      const target = resolveTypeName(program, candidate, importStyle);\n\n      // The replacement name is already bound to something else in this file,\n      // so rewriting to it would resolve to the wrong declaration.\n      return target === undefined\n        ? []\n        : [\n            {\n              messageId: messageIds.suggestion,\n              data: { name: stdName, replacement: target.localName },\n              fix: (fixer: TSESLint.RuleFixer): readonly TSESLint.RuleFix[] =>\n                Arr.toPushed(\n                  target.needsImport\n                    ? buildTypeImportFix(fixer, program, candidate)\n                    : [],\n                  fixer.replaceText(typeName, target.localName),\n                ),\n            },\n          ];\n    }),\n  });\n};\n\n/** `['StrictPick', 'RelaxedPick']` → `` '`StrictPick` or `RelaxedPick`' ``. */\nconst formatAlternatives = (candidates: readonly string[]): string =>\n  candidates.map((candidate) => `\\`${candidate}\\``).join(' or ');\n"],"names":[],"mappings":";;;;;;AA4BO,MAAM,yBAAyB,CACpC,OAAA,EACA,IAAA,EACA,YAAA,EACA,YACA,WAAA,KACS;AACT,EAAA,MAAM,WAAW,IAAA,CAAK,QAAA;AAGtB,EAAA,IAAI,QAAA,CAAS,IAAA,KAAS,cAAA,CAAe,UAAA,EAAY;AAEjD,EAAA,MAAM,UAAU,QAAA,CAAS,IAAA;AAEzB,EAAA,MAAM,UAAA,GAAa,YAAA,CAAa,GAAA,CAAI,OAAO,CAAA;AAE3C,EAAA,IAAI,eAAe,MAAA,EAAW;AAI9B,EAAA,IAAI,cAAA,CAAe,OAAA,CAAQ,UAAA,EAAY,IAAA,EAAM,OAAO,CAAA,EAAG;AAEvD,EAAA,MAAM,OAAA,GAAU,QAAQ,UAAA,CAAW,GAAA;AAEnC,EAAA,OAAA,CAAQ,MAAA,CAAO;AAAA,IACb,IAAA,EAAM,QAAA;AAAA,IACN,WAAW,UAAA,CAAW,MAAA;AAAA,IACtB,MAAM,EAAE,IAAA,EAAM,SAAS,YAAA,EAAc,kBAAA,CAAmB,UAAU,CAAA,EAAE;AAAA,IACpE,OAAA,EAAS,UAAA,CAAW,OAAA,CAAQ,CAAC,SAAA,KAAc;AACzC,MAAA,MAAM,MAAA,GAAS,eAAA,CAAgB,OAAA,EAAS,SAAA,EAAW,WAAW,CAAA;AAI9D,MAAA,OAAO,MAAA,KAAW,MAAA,GACd,EAAC,GACD;AAAA,QACE;AAAA,UACE,WAAW,UAAA,CAAW,UAAA;AAAA,UACtB,MAAM,EAAE,IAAA,EAAM,OAAA,EAAS,WAAA,EAAa,OAAO,SAAA,EAAU;AAAA,UACrD,GAAA,EAAK,CAAC,KAAA,KACJ,GAAA,CAAI,QAAA;AAAA,YACF,OAAO,WAAA,GACH,kBAAA,CAAmB,OAAO,OAAA,EAAS,SAAS,IAC5C,EAAC;AAAA,YACL,KAAA,CAAM,WAAA,CAAY,QAAA,EAAU,MAAA,CAAO,SAAS;AAAA;AAC9C;AACJ,OACF;AAAA,IACN,CAAC;AAAA,GACF,CAAA;AACH;AAGA,MAAM,kBAAA,GAAqB,CAAC,UAAA,KAC1B,UAAA,CAAW,GAAA,CAAI,CAAC,SAAA,KAAc,CAAA,EAAA,EAAK,SAAS,CAAA,EAAA,CAAI,CAAA,CAAE,IAAA,CAAK,MAAM,CAAA;;;;"}
+{"version":3,"file":"std-type-rule-utils.mjs","sourceRoot":"","sources":["../../src/rules/std-type-rule-utils.mts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,GAGf,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAoB,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAUxD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACpC,OAA6D,EAC7D,IAA8B,EAC9B,YAAiC,EACjC,UAAoE,EACpE,WAAwB,EAClB,EAAE;IACR,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAE/B,yEAAyE;IACzE,IAAI,QAAQ,CAAC,IAAI,KAAK,cAAc,CAAC,UAAU;QAAE,OAAO;IAExD,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC;IAE9B,MAAM,UAAU,GAAG,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAE7C,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO;IAErC,uEAAuE;IACvE,sDAAsD;IACtD,IAAI,cAAc,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC;QAAE,OAAO;IAE9D,MAAM,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;IAEvC,OAAO,CAAC,MAAM,CAAC;QACb,IAAI,EAAE,QAAQ;QACd,SAAS,EAAE,UAAU,CAAC,MAAM;QAC5B,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,kBAAkB,CAAC,UAAU,CAAC,EAAE;QACrE,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,EAAE;YACxC,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;YAEhE,wEAAwE;YACxE,6DAA6D;YAC7D,OAAO,MAAM,KAAK,SAAS;gBACzB,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC;oBACE;wBACE,SAAS,EAAE,UAAU,CAAC,UAAU;wBAChC,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,SAAS,EAAE;wBACtD,GAAG,EAAE,CAAC,KAAyB,EAA+B,EAAE,CAC9D,GAAG,CAAC,QAAQ,CACV,MAAM,CAAC,WAAW;4BAChB,CAAC,CAAC,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC;4BAC/C,CAAC,CAAC,EAAE,EACN,KAAK,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,CAC9C;qBACJ;iBACF,CAAC;QACR,CAAC,CAAC;KACH,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,+EAA+E;AAC/E,MAAM,kBAAkB,GAAG,CAAC,UAA6B,EAAU,EAAE,CACnE,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC"}

package/dist/types.mjs

@@ -1,2 +1,2 @@
-
-//# sourceMappingURL=types.mjs.map
+export {};
+//# sourceMappingURL=types.mjs.map

package/dist/types.mjs.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-ts-type-forge",
-  "version": "0.7.3",
+  "version": "0.8.1",
   "private": false,
   "description": "ESLint rules that steer type declarations toward ts-type-forge idioms.",
   "keywords": [
@@ -36,21 +36,20 @@
   ],
   "dependencies": {
     "@typescript-eslint/utils": "~8.68.0",
-    "ts-data-forge": "~14.6.1",
+    "ts-data-forge": "~14.6.3",
     "ts-type-forge": "9.2.2"
   },
   "devDependencies": {
     "@typescript-eslint/parser": "8.68.0",
     "@typescript-eslint/rule-tester": "8.68.0",
     "dedent": "1.7.2",
-    "eslint-config-typed": "5.10.2",
-    "eslint-plugin-ts-data-forge": "0.5.4",
-    "eslint-plugin-ts-fortress": "1.0.7",
+    "eslint-config-typed": "5.11.2",
+    "eslint-plugin-ts-data-forge": "0.7.0",
+    "eslint-plugin-ts-fortress": "1.2.0",
     "prettier": "3.9.6",
     "prettier-plugin-organize-imports": "4.3.0",
     "prettier-plugin-packagejson": "3.0.2",
-    "rollup": "4.62.5",
-    "ts-repo-utils": "10.4.0"
+    "ts-repo-utils": "10.6.0"
   },
   "peerDependencies": {
     "eslint": ">=9.0.0",

package/src/plugin.mts

@@ -8,6 +8,7 @@ import { type ESLintFlatConfig, type ESLintPlugin } from './types.mjs';
  * a rule without listing it here fails to type-check.
  */
 const recommendedRules = {
+  'ts-type-forge/no-side-effect-import': 'error',
   'ts-type-forge/prefer-canonical-length-constrained-tuple': 'error',
   'ts-type-forge/prefer-canonical-mutable-record': 'error',
   'ts-type-forge/prefer-readonly-or-mutable-record': 'error',

package/src/rule-types.mts

@@ -27,6 +27,21 @@ type RuleOptionsOf<Name extends keyof typeof tsTypeForgeRules> =
     ? Options
     : never;
 
+/**
+ * @description Remove a side-effect-only `import 'ts-type-forge';`, which binds no name and has no runtime entry point to resolve to. `ts-type-forge/global` is left alone.
+ *
+ *  ```md
+ *  | key        | value   |
+ *  | :--------- | :------ |
+ *  | type       | problem |
+ *  | deprecated | false   |
+ *  | fixable    | code    |
+ *  ```
+ */
+namespace NoSideEffectImport {
+  export type RuleEntry = Linter.StringSeverity;
+}
+
 /**
  * @description Replace uniform tuple spellings such as `[V, ...V[]]` / `[V, V, ...V[]]` / `[V, V, V]` with the canonical ts-type-forge tuple type.
  *
@@ -209,6 +224,7 @@ namespace PreferStrictOrRelaxedUtilityType {
 }
 
 export type EslintTsTypeForgeRules = Readonly<{
+  'ts-type-forge/no-side-effect-import': NoSideEffectImport.RuleEntry;
   'ts-type-forge/prefer-canonical-length-constrained-tuple': PreferCanonicalLengthConstrainedTuple.RuleEntry;
   'ts-type-forge/prefer-canonical-mutable-record': PreferCanonicalMutableRecord.RuleEntry;
   'ts-type-forge/prefer-readonly-or-mutable-record': PreferReadonlyOrMutableRecord.RuleEntry;

package/src/rules/no-side-effect-import.mts

@@ -0,0 +1,73 @@
+import { type TSESLint, type TSESTree } from '@typescript-eslint/utils';
+import { Arr } from 'ts-data-forge';
+import { TS_TYPE_FORGE_MODULE } from './constants.mjs';
+
+type Options = readonly [];
+
+type MessageIds = 'removeSideEffectImport';
+
+/**
+ * `import 'ts-type-forge';` binds nothing, and there is nothing for it to run:
+ * the package ships declarations only, and its `exports` map offers no runtime
+ * condition at all, so the import fails to resolve the moment the module graph
+ * is loaded. TypeScript keeps a side-effect import in the emitted JavaScript —
+ * that is the one kind it never elides — so this is a runtime error waiting in
+ * a file that type-checks.
+ *
+ * The ambient globals are a separate entry point, `ts-type-forge/global`,
+ * usually brought in through `compilerOptions.types` or a triple-slash
+ * reference. This rule matches the bare specifier exactly, so that subpath is
+ * left alone.
+ */
+export const noSideEffectImport: TSESLint.RuleModule<MessageIds, Options> = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: `Remove a side-effect-only \`import '${TS_TYPE_FORGE_MODULE}';\`, which binds no name and has no runtime entry point to resolve to. \`${TS_TYPE_FORGE_MODULE}/global\` is left alone.`,
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      removeSideEffectImport: `\`import '${TS_TYPE_FORGE_MODULE}';\` binds no name, and \`${TS_TYPE_FORGE_MODULE}\` ships types only — it has no runtime entry point, so the import throws when the module is loaded. Remove it; the ambient globals come from \`${TS_TYPE_FORGE_MODULE}/global\`, not from this.`,
+    },
+  },
+
+  create: (context) => ({
+    ImportDeclaration: (node) => {
+      if (
+        node.source.value !== TS_TYPE_FORGE_MODULE ||
+        !Arr.isEmpty(node.specifiers)
+      ) {
+        return;
+      }
+
+      context.report({
+        node,
+        messageId: 'removeSideEffectImport',
+        fix: (fixer) => removeStatement(fixer, context.sourceCode, node),
+      });
+    },
+  }),
+  defaultOptions: [],
+} as const;
+
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types */
+
+/**
+ * Removes a statement along with the rest of its line, so that deleting it does
+ * not leave a blank line where it was.
+ */
+const removeStatement = (
+  fixer: TSESLint.RuleFixer,
+  sourceCode: TSESLint.SourceCode,
+  node: TSESTree.Node,
+): TSESLint.RuleFix => {
+  const restOfLine = /^[^\S\n]*\n/u.exec(
+    sourceCode.getText().slice(node.range[1]),
+  );
+
+  return fixer.removeRange([
+    node.range[0],
+    node.range[1] + (restOfLine?.[0].length ?? 0),
+  ]);
+};

package/src/rules/no-side-effect-import.test.mts

@@ -0,0 +1,83 @@
+import parser from '@typescript-eslint/parser';
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import dedent from 'dedent';
+import { noSideEffectImport } from './no-side-effect-import.mjs';
+
+const tester = new RuleTester({
+  languageOptions: {
+    parser,
+    parserOptions: { ecmaVersion: 2020, sourceType: 'module' },
+  },
+});
+
+describe('no-side-effect-import', () => {
+  tester.run('no-side-effect-import', noSideEffectImport, {
+    valid: [
+      {
+        name: 'accepts a named import',
+        code: dedent`
+          import { type NonEmptyArray } from 'ts-type-forge';
+
+          export type Names = NonEmptyArray<string>;
+        `,
+      },
+      {
+        name: 'leaves the ambient globals entry point alone',
+        code: dedent`
+          import 'ts-type-forge/global';
+        `,
+      },
+      {
+        name: 'leaves other side-effect imports alone',
+        code: dedent`
+          import './polyfills.mjs';
+          import 'ts-type-forge-extras';
+        `,
+      },
+    ],
+    invalid: [
+      {
+        name: 'removes a side-effect-only import',
+        code: dedent`
+          import 'ts-type-forge';
+        `,
+        output: '',
+        errors: [{ messageId: 'removeSideEffectImport' }],
+      },
+      {
+        name: 'removes it along with its line',
+        code: dedent`
+          import 'ts-type-forge';
+          import { type Uint32 } from 'ts-type-forge';
+
+          export type Size = Uint32;
+        `,
+        output: dedent`
+          import { type Uint32 } from 'ts-type-forge';
+
+          export type Size = Uint32;
+        `,
+        errors: [{ messageId: 'removeSideEffectImport' }],
+      },
+      {
+        name: 'removes every side-effect-only import',
+        code: dedent`
+          import 'ts-type-forge';
+          import 'ts-type-forge/global';
+          import 'ts-type-forge';
+
+          export type Size = number;
+        `,
+        output: dedent`
+          import 'ts-type-forge/global';
+
+          export type Size = number;
+        `,
+        errors: [
+          { messageId: 'removeSideEffectImport' },
+          { messageId: 'removeSideEffectImport' },
+        ],
+      },
+    ],
+  });
+});

package/src/rules/rules.mts

@@ -1,10 +1,12 @@
 import { type ESLintPlugin } from '../types.mjs';
+import { noSideEffectImport } from './no-side-effect-import.mjs';
 import { preferCanonicalLengthConstrainedTuple } from './prefer-canonical-length-constrained-tuple.mjs';
 import { preferCanonicalMutableRecord } from './prefer-canonical-mutable-record.mjs';
 import { preferReadonlyOrMutableRecord } from './prefer-readonly-or-mutable-record.mjs';
 import { preferStrictOrRelaxedUtilityType } from './prefer-strict-or-relaxed-utility-type.mjs';
 
 export const tsTypeForgeRules = {
+  'no-side-effect-import': noSideEffectImport,
   'prefer-canonical-length-constrained-tuple':
     preferCanonicalLengthConstrainedTuple,
   'prefer-canonical-mutable-record': preferCanonicalMutableRecord,