eslint-rule-forge 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,191 @@
-# Temporary Holding Version
+# eslint-rule-forge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Helpers for writing [typescript-eslint](https://typescript-eslint.io/) rules
+that are hard to fool: they see through type wrappers and parentheses, and
+resolve what a file imports however it is written.
+
+A rule that matches `Number(x)` but not `(Number as NumberConstructor)(x)` has
+a hole a wrapper slips through, and one that asks the type of `x as string`
+trusts a claim the checker never verified. These are the helpers the
+`eslint-plugin-ts-*` packages and `eslint-config-typed` share for that, in one
+place, so that a fix to one of them reaches every rule.
+
+## Installation
+
+```sh
+npm install eslint-rule-forge
+```
+
+`@typescript-eslint/utils` comes with it; `eslint` and `typescript` are peer
+dependencies.
+
+## Type wrappers
+
+`x as T`, `x!`, `x satisfies T` and `<T>x` change a type and never a value.
+
+| Helper              | What it gives                                                                         |
+| :------------------ | :------------------------------------------------------------------------------------ |
+| `isTypeWrapper`     | whether a node is one of the four                                                     |
+| `skipTypeWrappers`  | the expression inside every wrapper around a node: judge syntax on this               |
+| `typeWrapperLayers` | the node and every expression inside its wrappers, outermost first: ask types of each |
+| `TypeWrapper`       | the four node types                                                                   |
+
+All of them take a readonly (`DeepReadonly<TSESTree.Node>`) or a mutable node
+and give back the same kind.
+
+Judge syntax on what `skipTypeWrappers` returns, and write the fix from the
+original node, so that the wrapper is kept:
+
+```ts
+import { AST_NODE_TYPES, type TSESLint } from '@typescript-eslint/utils';
+import { getArgumentText, skipTypeWrappers } from 'eslint-rule-forge';
+
+// Reports `Number(x)`, also written `(Number as NumberConstructor)(x)` or
+// `Number!(x)`, and rewrites it to `toNumber(x)`.
+export const noNumberCall: TSESLint.RuleModule<'noNumberCall'> = {
+    meta: {
+        type: 'suggestion',
+        messages: { noNumberCall: 'Use `toNumber` instead of `Number`.' },
+        fixable: 'code',
+        schema: [],
+    },
+    defaultOptions: [],
+    create: (context) => ({
+        CallExpression: (node) => {
+            // Judge the syntax on the expression inside the wrappers ...
+            const callee = skipTypeWrappers(node.callee);
+
+            const [argument] = node.arguments;
+
+            if (
+                argument === undefined ||
+                callee.type !== AST_NODE_TYPES.Identifier ||
+                callee.name !== 'Number'
+            ) {
+                return;
+            }
+
+            context.report({
+                node,
+                messageId: 'noNumberCall',
+                // ... and write the fix from the original nodes, keeping a sequence
+                // argument `(a, b)` one argument.
+                fix: (fixer) =>
+                    fixer.replaceText(
+                        node,
+                        `toNumber(${getArgumentText(context.sourceCode, argument)})`,
+                    ),
+            });
+        },
+    }),
+} as const;
+```
+
+A conclusion drawn from a type — that a guard always holds, that a value is an
+array — has to hold at every layer `typeWrapperLayers` returns. A widening
+assertion (`x as string | null`) then makes the rule more cautious, and a
+narrowing one (`x!`, `v as string` on an `unknown`), which the checker cannot
+verify, changes nothing.
+
+## Parentheses
+
+The range and the text of a node leave out the parentheses written around it.
+
+| Helper               | What it gives                                                       |
+| :------------------- | :------------------------------------------------------------------ |
+| `parenthesesDepth`   | how many pairs of parentheses surround a node                       |
+| `getRangeWithParens` | the node's range including them                                     |
+| `getArgumentText`    | the node's text for an argument list, `(a, b)` kept as one argument |
+
+## Imports and bindings
+
+| Helper                  | What it gives                                                                                        |
+| :---------------------- | :--------------------------------------------------------------------------------------------------- |
+| `getImportDeclarations` | every `import … from '<module>'` in the file, not only the first                                     |
+| `getNamedImports`       | the export names those declarations import                                                           |
+| `getImportedLocalName`  | the local name an export is imported as (`'y'` for `import { x as y }`)                              |
+| `buildCalleeResolver`   | which export a callee calls, through aliases, namespace imports and type wrappers                    |
+| `buildNamedImportFix`   | a fix inserting `import { … } from '<module>';`, for an import sorter to place                       |
+| `hasForeignBinding`     | whether a name, at a node, is bound to something other than the module's import (a fix must give up) |
+| `isLocallyBound`        | whether a name, at a node, is declared in the file rather than a global or a standard-library type   |
+
+```ts
+import type { TSESLint } from '@typescript-eslint/utils';
+import {
+    buildCalleeResolver,
+    buildNamedImportFix,
+    getImportDeclarations,
+    getImportedLocalName,
+    hasForeignBinding,
+} from 'eslint-rule-forge';
+
+const MODULE = 'my-lib';
+
+// Rewrites a call to `isNull` from `my-lib`, however it is imported, to
+// `isNullish` from the same module, adding the import when it is missing.
+export const preferIsNullish: TSESLint.RuleModule<'preferIsNullish'> = {
+    meta: {
+        type: 'suggestion',
+        messages: { preferIsNullish: 'Use `isNullish`.' },
+        fixable: 'code',
+        schema: [],
+    },
+    defaultOptions: [],
+    create: (context) => {
+        const program = context.sourceCode.ast;
+
+        const declarations = getImportDeclarations(program, MODULE);
+
+        // `isNull(x)`, `n(x)` after `import { isNull as n }` and `lib.isNull(x)`
+        // after `import * as lib` all call `isNull`.
+        const resolve = buildCalleeResolver(declarations);
+
+        return {
+            CallExpression: (node) => {
+                const resolved = resolve(node.callee);
+
+                if (resolved?.canonicalName !== 'isNull') {
+                    return;
+                }
+
+                const importedAs = getImportedLocalName(
+                    declarations,
+                    'isNullish',
+                );
+
+                const name = resolved.isNamespace
+                    ? 'isNullish'
+                    : (importedAs ?? 'isNullish');
+
+                // A local `isNullish` that is not `my-lib`'s would capture the call.
+                const canFix =
+                    resolved.isNamespace ||
+                    !hasForeignBinding(context.sourceCode, node, name, MODULE);
+
+                context.report({
+                    node,
+                    messageId: 'preferIsNullish',
+                    fix: canFix
+                        ? (fixer) => [
+                              ...(importedAs !== undefined ||
+                              resolved.isNamespace
+                                  ? []
+                                  : buildNamedImportFix(
+                                        fixer,
+                                        program,
+                                        MODULE,
+                                        [name],
+                                    )),
+                              fixer.replaceText(resolved.propertyNode, name),
+                          ]
+                        : null,
+                });
+            },
+        };
+    },
+} as const;
+```
+
+## License
+
+[Apache-2.0](https://github.com/noshiro-pf/mono/blob/main/libs/eslint-rule-forge/LICENSE)

package/dist/bindings.d.mts

@@ -0,0 +1,23 @@
+import { type TSESLint, type TSESTree } from '@typescript-eslint/utils';
+/**
+ * Whether `name`, read at `node`, resolves to something this file writes down
+ * — a declaration, a parameter, an import — rather than to a global or a
+ * standard-library type of the same name.
+ *
+ * The scope manager makes an implicit variable for every reference it cannot
+ * resolve, so `findVariable` finds `Exclude` in a file that never declares it;
+ * only a variable with a definition was written in the file.
+ */
+export declare const isLocallyBound: (sourceCode: TSESLint.SourceCode, node: TSESTree.Node, name: string) => boolean;
+/**
+ * Whether `name`, read at `node`, resolves to a binding that is not an import
+ * from `moduleName` — a declaration, a parameter, or an import from another
+ * module. A fix that makes code at `node` refer to `moduleName`'s export
+ * `name` has to give up then, because the name would refer to that binding
+ * instead.
+ *
+ * The innermost binding decides: an import from `moduleName` at the top of the
+ * file does not help a name a function shadows around `node`.
+ */
+export declare const hasForeignBinding: (sourceCode: TSESLint.SourceCode, node: TSESTree.Node, name: string, moduleName: string) => boolean;
+//# sourceMappingURL=bindings.d.mts.map

package/dist/bindings.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.d.mts","sourceRoot":"","sources":["../src/bindings.mts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,QAAQ,EACd,MAAM,0BAA0B,CAAC;AAIlC;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,eACb,QAAQ,CAAC,UAAU,QACzB,QAAQ,CAAC,IAAI,QACb,MAAM,KACX,OAIF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,eAChB,QAAQ,CAAC,UAAU,QACzB,QAAQ,CAAC,IAAI,QACb,MAAM,cACA,MAAM,KACjB,OAIF,CAAC"}

package/dist/bindings.mjs

@@ -0,0 +1,39 @@
+import { AST_NODE_TYPES, ASTUtils, } from '@typescript-eslint/utils';
+
+
+
+
+
+
+
+
+
+
+export const isLocallyBound = (sourceCode, node, name) => {
+    const variable = ASTUtils.findVariable(sourceCode.getScope(node), name);
+    return variable !== null && variable.defs.length > 0;
+};
+
+
+
+
+
+
+
+
+
+
+export const hasForeignBinding = (sourceCode, node, name, moduleName) => {
+    const variable = ASTUtils.findVariable(sourceCode.getScope(node), name);
+    return variable?.defs.some((def) => !isImportFrom(def, moduleName)) ?? false;
+};
+
+
+
+
+const isImportFrom = (def, moduleName) => (def.node.type === AST_NODE_TYPES.ImportSpecifier ||
+    def.node.type === AST_NODE_TYPES.ImportDefaultSpecifier ||
+    def.node.type === AST_NODE_TYPES.ImportNamespaceSpecifier) &&
+    def.node.parent.type === AST_NODE_TYPES.ImportDeclaration &&
+    def.node.parent.source.value === moduleName;
+//# sourceMappingURL=bindings.mjs.map

package/dist/bindings.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.mjs","sourceRoot":"","sources":["../src/bindings.mts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,QAAQ,GAGT,MAAM,0BAA0B,CAAC;AAElC,uEAAuE;AAEvE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,UAA+B,EAC/B,IAAmB,EACnB,IAAY,EACH,EAAE;IACX,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IAExE,OAAO,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;AACvD,CAAC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,UAA+B,EAC/B,IAAmB,EACnB,IAAY,EACZ,UAAkB,EACT,EAAE;IACX,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IAExE,OAAO,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,IAAI,KAAK,CAAC;AAC/E,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,YAAY,GAAG,CACnB,GAA8B,EAC9B,UAAkB,EACT,EAAE,CACX,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC,eAAe;IAC/C,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC,sBAAsB;IACvD,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC,wBAAwB,CAAC;IAC5D,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,cAAc,CAAC,iBAAiB;IACzD,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,KAAK,UAAU,CAAC"}

package/dist/imports.d.mts

@@ -0,0 +1,54 @@
+import { type TSESLint, type TSESTree } from '@typescript-eslint/utils';
+import type { DeepReadonly } from 'ts-type-forge';
+/**
+ * Every `import … from '<moduleName>'` declaration in the file, not only the
+ * first: `import type { A } from 'm'` and `import { b } from 'm'` are two
+ * declarations, and a name imported by either is in scope.
+ */
+export declare const getImportDeclarations: (program: TSESTree.Program, moduleName: string) => readonly TSESTree.ImportDeclaration[];
+/**
+ * The exported names `declarations` import by name, whatever they are bound to
+ * locally: `import { a, b as c }` gives `a` and `b`.
+ */
+export declare const getNamedImports: (declarations: DeepReadonly<TSESTree.ImportDeclaration[]>) => readonly string[];
+/**
+ * The local name `declarations` bind the export `importedName` to, or
+ * `undefined` when they do not import it: `'y'` for `import { x as y }`. A fix
+ * writes this rather than the exported name, which may not be in scope.
+ */
+export declare const getImportedLocalName: (declarations: DeepReadonly<TSESTree.ImportDeclaration[]>, importedName: string) => string | undefined;
+/** What {@link buildCalleeResolver}'s resolver says a callee calls. */
+export type ResolvedCallee = Readonly<{
+    /** The exported name, whatever the callee calls it locally. */
+    canonicalName: string;
+    /**
+     * The identifier to rewrite to change what is called: the callee itself for
+     * a named import, the property for a namespace import.
+     */
+    propertyNode: TSESTree.Identifier;
+    /** Whether the call goes through a namespace import (`m.f(...)`). */
+    isNamespace: boolean;
+}>;
+/**
+ * Builds a function that says which export of the module `declarations`
+ * import a callee calls, or `undefined` when it calls none of them. It knows
+ * named imports, aliased ones (`import { f as g }` → `g(...)` calls `f`) and
+ * namespace imports (`import * as m` → `m.f(...)`), and reads both the callee
+ * and a namespace object through their type wrappers:
+ * `(f as (u: unknown) => boolean)(x)` and `(m as typeof m).f(x)` still call
+ * `f`.
+ */
+export declare const buildCalleeResolver: (declarations: DeepReadonly<TSESTree.ImportDeclaration[]>) => ((callee: TSESTree.Expression) => ResolvedCallee | undefined);
+/**
+ * A fix that inserts `import { <specifiers> } from '<moduleName>';` at the top
+ * of the file, or no fix when `specifiers` is empty. Each specifier is written
+ * as given, so `type T` imports a type.
+ *
+ * The placement is deliberately naive: an import sorter
+ * (prettier-plugin-organize-imports or any equivalent) merges and orders it
+ * afterwards. Put every name one report needs into a single call: ESLint
+ * merges the fixes of one report into one edit, and two fixes inserting at the
+ * start of the file conflict, so that one of them is dropped.
+ */
+export declare const buildNamedImportFix: (fixer: TSESLint.RuleFixer, program: TSESTree.Program, moduleName: string, specifiers: readonly string[]) => readonly TSESLint.RuleFix[];
+//# sourceMappingURL=imports.d.mts.map

package/dist/imports.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imports.d.mts","sourceRoot":"","sources":["../src/imports.mts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,QAAQ,EACd,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAKlD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,YACvB,QAAQ,CAAC,OAAO,cACb,MAAM,KACjB,SAAS,QAAQ,CAAC,iBAAiB,EAKnC,CAAC;AAEJ;;;GAGG;AACH,eAAO,MAAM,eAAe,iBACZ,YAAY,CAAC,QAAQ,CAAC,iBAAiB,EAAE,CAAC,KACvD,SAAS,MAAM,EAOf,CAAC;AAEJ;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,iBACjB,YAAY,CAAC,QAAQ,CAAC,iBAAiB,EAAE,CAAC,gBAC1C,MAAM,KACnB,MAAM,GAAG,SAOK,CAAC;AAElB,uEAAuE;AACvE,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,YAAY,EAAE,QAAQ,CAAC,UAAU,CAAC;IAElC,qEAAqE;IACrE,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,iBAChB,YAAY,CAAC,QAAQ,CAAC,iBAAiB,EAAE,CAAC,KACvD,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,KAAK,cAAc,GAAG,SAAS,CAuD9D,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,UACvB,QAAQ,CAAC,SAAS,WAChB,QAAQ,CAAC,OAAO,cACb,MAAM,cACN,SAAS,MAAM,EAAE,KAC5B,SAAS,QAAQ,CAAC,OAAO,EAQX,CAAC"}

package/dist/imports.mjs

@@ -0,0 +1,90 @@
+import { AST_NODE_TYPES, } from '@typescript-eslint/utils';
+import { isTypeWrapper, skipTypeWrappers } from './type-wrappers.mjs';
+
+
+
+
+
+
+export const getImportDeclarations = (program, moduleName) => program.body.filter((node) => node.type === AST_NODE_TYPES.ImportDeclaration &&
+    node.source.value === moduleName);
+
+
+
+
+export const getNamedImports = (declarations) => declarations.flatMap((declaration) => declaration.specifiers.flatMap((specifier) => specifier.type === AST_NODE_TYPES.ImportSpecifier
+    ? [importedNameOf(specifier)]
+    : []));
+
+
+
+
+
+export const getImportedLocalName = (declarations, importedName) => declarations
+    .flatMap((declaration) => declaration.specifiers)
+    .find((specifier) => specifier.type === AST_NODE_TYPES.ImportSpecifier &&
+    importedNameOf(specifier) === importedName)?.local.name;
+
+
+
+
+
+
+
+
+
+export const buildCalleeResolver = (declarations) => {
+    const specifiers = declarations.flatMap((declaration) => declaration.specifiers);
+    const namespaceNames = new Set(specifiers.flatMap((specifier) => specifier.type === AST_NODE_TYPES.ImportNamespaceSpecifier
+        ? [specifier.local.name]
+        : []));
+    const localToCanonical = new Map(specifiers.flatMap((specifier) => specifier.type === AST_NODE_TYPES.ImportSpecifier
+        ? [[specifier.local.name, importedNameOf(specifier)]]
+        : []));
+    const resolve = (callee) => {
+        if (isTypeWrapper(callee)) {
+            return resolve(callee.expression);
+        }
+        if (callee.type === AST_NODE_TYPES.Identifier) {
+            const canonicalName = localToCanonical.get(callee.name);
+            return canonicalName === undefined
+                ? undefined
+                : { canonicalName, propertyNode: callee, isNamespace: false };
+        }
+        if (callee.type !== AST_NODE_TYPES.MemberExpression ||
+            callee.computed ||
+            callee.property.type !== AST_NODE_TYPES.Identifier) {
+            return undefined;
+        }
+        const object = skipTypeWrappers(callee.object);
+        return object.type === AST_NODE_TYPES.Identifier &&
+            namespaceNames.has(object.name)
+            ? {
+                canonicalName: callee.property.name,
+                propertyNode: callee.property,
+                isNamespace: true,
+            }
+            : undefined;
+    };
+    return resolve;
+};
+
+
+
+
+
+
+
+
+
+
+
+export const buildNamedImportFix = (fixer, program, moduleName, specifiers) => specifiers.length === 0
+    ? []
+    : [
+        fixer.insertTextBefore(program, `import { ${specifiers.join(', ')} } from '${moduleName}';\n`),
+    ];
+const importedNameOf = (specifier) => specifier.imported.type === AST_NODE_TYPES.Identifier
+    ? specifier.imported.name
+    : specifier.imported.value;
+//# sourceMappingURL=imports.mjs.map

package/dist/imports.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"imports.mjs","sourceRoot":"","sources":["../src/imports.mts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,GAGf,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEtE,uEAAuE;AAEvE;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACnC,OAAyB,EACzB,UAAkB,EACqB,EAAE,CACzC,OAAO,CAAC,IAAI,CAAC,MAAM,CACjB,CAAC,IAAI,EAAsC,EAAE,CAC3C,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC,iBAAiB;IAC9C,IAAI,CAAC,MAAM,CAAC,KAAK,KAAK,UAAU,CACnC,CAAC;AAEJ;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,YAAwD,EACrC,EAAE,CACrB,YAAY,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,EAAE,CACnC,WAAW,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,EAAE,CAC3C,SAAS,CAAC,IAAI,KAAK,cAAc,CAAC,eAAe;IAC/C,CAAC,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;IAC7B,CAAC,CAAC,EAAE,CACP,CACF,CAAC;AAEJ;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,YAAwD,EACxD,YAAoB,EACA,EAAE,CACtB,YAAY;KACT,OAAO,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,UAAU,CAAC;KAChD,IAAI,CACH,CAAC,SAAS,EAAE,EAAE,CACZ,SAAS,CAAC,IAAI,KAAK,cAAc,CAAC,eAAe;IACjD,cAAc,CAAC,SAAS,CAAC,KAAK,YAAY,CAC7C,EAAE,KAAK,CAAC,IAAI,CAAC;AAiBlB;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,YAAwD,EACO,EAAE;IACjE,MAAM,UAAU,GAAG,YAAY,CAAC,OAAO,CACrC,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,UAAU,CACxC,CAAC;IAEF,MAAM,cAAc,GAAwB,IAAI,GAAG,CACjD,UAAU,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,EAAE,CAC/B,SAAS,CAAC,IAAI,KAAK,cAAc,CAAC,wBAAwB;QACxD,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC;QACxB,CAAC,CAAC,EAAE,CACP,CACF,CAAC;IAEF,MAAM,gBAAgB,GAAgC,IAAI,GAAG,CAC3D,UAAU,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,EAAE,CAC/B,SAAS,CAAC,IAAI,KAAK,cAAc,CAAC,eAAe;QAC/C,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,cAAc,CAAC,SAAS,CAAC,CAAU,CAAC;QAC9D,CAAC,CAAC,EAAE,CACP,CACF,CAAC;IAEF,MAAM,OAAO,GAAG,CAAC,MAA2B,EAA8B,EAAE;QAC1E,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,OAAO,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACpC,CAAC;QAED,IAAI,MAAM,CAAC,IAAI,KAAK,cAAc,CAAC,UAAU,EAAE,CAAC;YAC9C,MAAM,aAAa,GAAG,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAExD,OAAO,aAAa,KAAK,SAAS;gBAChC,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;QAClE,CAAC;QAED,IACE,MAAM,CAAC,IAAI,KAAK,cAAc,CAAC,gBAAgB;YAC/C,MAAM,CAAC,QAAQ;YACf,MAAM,CAAC,QAAQ,CAAC,IAAI,KAAK,cAAc,CAAC,UAAU,EAClD,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,MAAM,GAAG,gBAAgB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAE/C,OAAO,MAAM,CAAC,IAAI,KAAK,cAAc,CAAC,UAAU;YAC9C,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;YAC/B,CAAC,CAAC;gBACE,aAAa,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI;gBACnC,YAAY,EAAE,MAAM,CAAC,QAAQ;gBAC7B,WAAW,EAAE,IAAI;aAClB;YACH,CAAC,CAAC,SAAS,CAAC;IAChB,CAAC,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,KAAyB,EACzB,OAAyB,EACzB,UAAkB,EAClB,UAA6B,EACA,EAAE,CAC/B,UAAU,CAAC,MAAM,KAAK,CAAC;IACrB,CAAC,CAAE,EAAY;IACf,CAAC,CAAE;QACC,KAAK,CAAC,gBAAgB,CACpB,OAAO,EACP,YAAY,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,UAAU,MAAM,CAC9D;KACQ,CAAC;AAElB,MAAM,cAAc,GAAG,CACrB,SAAiD,EACzC,EAAE,CACV,SAAS,CAAC,QAAQ,CAAC,IAAI,KAAK,cAAc,CAAC,UAAU;IACnD,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI;IACzB,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC"}

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+export * from './bindings.mjs';
+export * from './imports.mjs';
+export * from './parentheses.mjs';
+export * from './type-wrappers.mjs';
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC"}

package/dist/index.mjs

@@ -0,0 +1,5 @@
+export * from './bindings.mjs';
+export * from './imports.mjs';
+export * from './parentheses.mjs';
+export * from './type-wrappers.mjs';
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC"}

package/dist/parentheses.d.mts

@@ -0,0 +1,21 @@
+import { type TSESLint, type TSESTree } from '@typescript-eslint/utils';
+import type { DeepReadonly } from 'ts-type-forge';
+/**
+ * How many pairs of parentheses the source puts around `node`: `0` for `a`, `2`
+ * for `((a))`. The parentheses of a call's argument list are not counted.
+ */
+export declare const parenthesesDepth: (sourceCode: TSESLint.SourceCode, node: DeepReadonly<TSESTree.Node>) => number;
+/**
+ * The range of `node` together with the parentheses the source puts around it,
+ * which `node.range` leaves out: all of `((Array.isArray))` for the member
+ * expression inside.
+ */
+export declare const getRangeWithParens: (sourceCode: TSESLint.SourceCode, node: DeepReadonly<TSESTree.Node>) => TSESTree.Range;
+/**
+ * The source text of `node` to put in a call's argument list. A node's text
+ * never includes the parentheses the source wrote around it, so a sequence
+ * expression gets them back here, whether or not the source had them:
+ * `(setup(), x)` would otherwise become two arguments.
+ */
+export declare const getArgumentText: (sourceCode: TSESLint.SourceCode, node: DeepReadonly<TSESTree.Node>) => string;
+//# sourceMappingURL=parentheses.d.mts.map

package/dist/parentheses.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parentheses.d.mts","sourceRoot":"","sources":["../src/parentheses.mts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,QAAQ,EACd,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAIlD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,eACf,QAAQ,CAAC,UAAU,QACzB,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,KAChC,MASF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,eACjB,QAAQ,CAAC,UAAU,QACzB,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,KAChC,QAAQ,CAAC,KAcX,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,eACd,QAAQ,CAAC,UAAU,QACzB,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,KAChC,MAIF,CAAC"}

package/dist/parentheses.mjs

@@ -0,0 +1,47 @@
+import { AST_NODE_TYPES, ASTUtils, } from '@typescript-eslint/utils';
+
+
+
+
+
+export const parenthesesDepth = (sourceCode, node) => {
+    const mutableNode = asNode(node);
+    const depthFrom = (known) => ASTUtils.isParenthesized(known + 1, mutableNode, sourceCode)
+        ? depthFrom(known + 1)
+        : known;
+    return depthFrom(0);
+};
+
+
+
+
+
+export const getRangeWithParens = (sourceCode, node) => {
+    const depth = parenthesesDepth(sourceCode, node);
+    if (depth === 0) {
+        return [node.range[0], node.range[1]];
+    }
+    const opening = sourceCode.getTokenBefore(asNode(node), { skip: depth - 1 });
+    const closing = sourceCode.getTokenAfter(asNode(node), { skip: depth - 1 });
+    return opening === null || closing === null
+        ? [node.range[0], node.range[1]]
+        : [opening.range[0], closing.range[1]];
+};
+
+
+
+
+
+
+export const getArgumentText = (sourceCode, node) => {
+    const text = sourceCode.text.slice(node.range[0], node.range[1]);
+    return node.type === AST_NODE_TYPES.SequenceExpression ? `(${text})` : text;
+};
+
+
+
+
+const asNode = (node) => 
+
+node;
+//# sourceMappingURL=parentheses.mjs.map

package/dist/parentheses.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"parentheses.mjs","sourceRoot":"","sources":["../src/parentheses.mts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,QAAQ,GAGT,MAAM,0BAA0B,CAAC;AAGlC,uEAAuE;AAEvE;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,UAA+B,EAC/B,IAAiC,EACzB,EAAE;IACV,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAEjC,MAAM,SAAS,GAAG,CAAC,KAAa,EAAU,EAAE,CAC1C,QAAQ,CAAC,eAAe,CAAC,KAAK,GAAG,CAAC,EAAE,WAAW,EAAE,UAAU,CAAC;QAC1D,CAAC,CAAC,SAAS,CAAC,KAAK,GAAG,CAAC,CAAC;QACtB,CAAC,CAAC,KAAK,CAAC;IAEZ,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC;AACtB,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,UAA+B,EAC/B,IAAiC,EACjB,EAAE;IAClB,MAAM,KAAK,GAAG,gBAAgB,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAEjD,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;QAChB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IAED,MAAM,OAAO,GAAG,UAAU,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC;IAE7E,MAAM,OAAO,GAAG,UAAU,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC;IAE5E,OAAO,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,IAAI;QACzC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAChC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3C,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,UAA+B,EAC/B,IAAiC,EACzB,EAAE;IACV,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAEjE,OAAO,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC,kBAAkB,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9E,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,GAAG,CAAC,IAAiC,EAAiB,EAAE;AAClE,oEAAoE;AACpE,IAAqB,CAAC"}

package/dist/type-wrappers.d.mts

@@ -0,0 +1,44 @@
+import { type TSESTree } from '@typescript-eslint/utils';
+import type { DeepReadonly, RelaxedExtract } from 'ts-type-forge';
+/**
+ * The four expressions that change a value's type and nothing else: `x as T`,
+ * `x!`, `x satisfies T` and `<T>x`.
+ */
+export type TypeWrapper = TSESTree.TSAsExpression | TSESTree.TSNonNullExpression | TSESTree.TSSatisfiesExpression | TSESTree.TSTypeAssertion;
+/**
+ * The expression a type wrapper among `N` wraps, as mutable or as readonly as
+ * `N` itself: `TSESTree.Expression` for a mutable node,
+ * `DeepReadonly<TSESTree.Expression>` for a readonly one, and `never` when no
+ * member of `N` is a type wrapper.
+ */
+export type WrappedExpression<N> = RelaxedExtract<N, DeepReadonly<TypeWrapper> | TypeWrapper>['expression'];
+/**
+ * Whether `node` is a type wrapper (see {@link TypeWrapper}). Takes a readonly
+ * or a mutable node and narrows it without changing which.
+ */
+export declare const isTypeWrapper: (node: DeepReadonly<TSESTree.Node>) => node is DeepReadonly<TypeWrapper> | TypeWrapper;
+/**
+ * `node` with every `as`, `satisfies`, `!` and `<T>` around it taken off: the
+ * expression whose value it is. A wrapper changes no value, so a rule judges
+ * syntax on what this returns — `xs.length > (0 as number)` compares with the
+ * literal `0`, and `(Number satisfies NumberConstructor)('1')` calls `Number` —
+ * and writes its fix from the original node, so that the wrapper is kept. A
+ * type is another matter: see {@link typeWrapperLayers}.
+ */
+export declare const skipTypeWrappers: <N extends DeepReadonly<TSESTree.Node>>(node: N) => N | WrappedExpression<N>;
+/**
+ * `node` and every expression inside the type wrappers around it, outermost
+ * first: `x as A as B` gives `x as A as B`, `x as A` and `x`, the last of which
+ * is `skipTypeWrappers(node)`.
+ *
+ * A conclusion a rule draws from a type — that a guard always holds, that a
+ * value is an array, that an operation may throw — has to hold for the type of
+ * every layer. An assertion therefore only ever makes a rule more cautious:
+ * one that widens (`x as string | null`) is the author saying the value may be
+ * `null`, and is respected; one that narrows (`x!`, `v as string` on an
+ * `unknown`) is a claim the checker cannot verify, and the value's own type
+ * still decides. The fix, which keeps the wrapper, has to type-check at every
+ * layer too.
+ */
+export declare const typeWrapperLayers: <N extends DeepReadonly<TSESTree.Node>>(node: N) => readonly (N | WrappedExpression<N>)[];
+//# sourceMappingURL=type-wrappers.d.mts.map

package/dist/type-wrappers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-wrappers.d.mts","sourceRoot":"","sources":["../src/type-wrappers.mts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAElE;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB,QAAQ,CAAC,cAAc,GACvB,QAAQ,CAAC,mBAAmB,GAC5B,QAAQ,CAAC,qBAAqB,GAC9B,QAAQ,CAAC,eAAe,CAAC;AAE7B;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,cAAc,CAC/C,CAAC,EACD,YAAY,CAAC,WAAW,CAAC,GAAG,WAAW,CACxC,CAAC,YAAY,CAAC,CAAC;AAEhB;;;GAGG;AACH,eAAO,MAAM,aAAa,SAClB,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,KAChC,IAAI,IAAI,YAAY,CAAC,WAAW,CAAC,GAAG,WACT,CAAC;AAE/B;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,QAC9D,CAAC,KACN,CAAC,GAAG,iBAAiB,CAAC,CAAC,CACsC,CAAC;AAEjE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,QAC/D,CAAC,KACN,SAAS,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAGf,CAAC"}

package/dist/type-wrappers.mjs

@@ -0,0 +1,39 @@
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+
+
+
+export const isTypeWrapper = (node) => TYPE_WRAPPERS.has(node.type);
+
+
+
+
+
+
+
+
+export const skipTypeWrappers = (node) => isTypeWrapper(node) ? skipTypeWrappers(node.expression) : node;
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+export const typeWrapperLayers = (node) => isTypeWrapper(node)
+    ? [node, ...typeWrapperLayers(node.expression)]
+    : [node];
+const TYPE_WRAPPERS = new Set([
+    AST_NODE_TYPES.TSAsExpression,
+    AST_NODE_TYPES.TSNonNullExpression,
+    AST_NODE_TYPES.TSSatisfiesExpression,
+    AST_NODE_TYPES.TSTypeAssertion,
+]);
+//# sourceMappingURL=type-wrappers.mjs.map

package/dist/type-wrappers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-wrappers.mjs","sourceRoot":"","sources":["../src/type-wrappers.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAiB,MAAM,0BAA0B,CAAC;AAwBzE;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,IAAiC,EACgB,EAAE,CACnD,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAE/B;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,IAAO,EACmB,EAAE,CAC5B,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAEjE;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,IAAO,EACgC,EAAE,CACzC,aAAa,CAAC,IAAI,CAAC;IACjB,CAAC,CAAE,CAAC,IAAI,EAAE,GAAG,iBAAiB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAW;IAC1D,CAAC,CAAE,CAAC,IAAI,CAAW,CAAC;AAExB,MAAM,aAAa,GAAgC,IAAI,GAAG,CAAC;IACzD,cAAc,CAAC,cAAc;IAC7B,cAAc,CAAC,mBAAmB;IAClC,cAAc,CAAC,qBAAqB;IACpC,cAAc,CAAC,eAAe;CAC/B,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,88 @@
 {
   "name": "eslint-rule-forge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "private": false,
+  "description": "Helpers for writing typescript-eslint rules that see through type wrappers and parentheses, and resolve what a file imports.",
+  "keywords": [
+    "eslint",
+    "typescript-eslint",
+    "eslint-rule",
+    "ast",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noshiro-pf/mono.git",
+    "directory": "libs/eslint-rule-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"
+  ],
+  "dependencies": {
+    "@typescript-eslint/utils": "^8.71.1",
+    "ts-type-forge": "~9.2.2"
+  },
+  "devDependencies": {
+    "@typescript-eslint/rule-tester": "8.71.1",
+    "dedent": "1.7.2",
+    "eslint": "10.12.0",
+    "eslint-config-typed": "5.17.4",
+    "eslint-plugin-ts-fortress": "1.3.3",
+    "eslint-plugin-ts-type-forge": "0.8.8",
+    "prettier": "3.9.9",
+    "prettier-plugin-organize-imports": "4.3.0",
+    "prettier-plugin-packagejson": "3.0.2",
+    "ts-data-forge": "14.7.1",
+    "ts-repo-utils": "10.7.1"
+  },
+  "peerDependencies": {
+    "eslint": ">=9.0.0",
+    "typescript": ">=5.0.0 <7.0.0"
+  },
+  "engines": {
+    "node": ">=22.22.2",
+    "pnpm": ">=9.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/build.mts",
+    "check:ext": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/check-ext.mts",
+    "check:lint": "oxlint . && eslint .",
+    "check:test": "pnpm run z:vitest run",
+    "check:test:cov": "pnpm run z:vitest run --coverage",
+    "check:types": "node ../../node_modules/typescript-native/bin/tsc --noEmit",
+    "doc": "pnpm run gen:readme",
+    "fix:fmt": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/format-uncommitted.mts --cwd .",
+    "fix:fmt:diff": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/format-diff-from.mts origin/main --cwd .",
+    "fix:fmt:full": "pnpm run z:prettier .",
+    "fix:lint": "oxlint . --fix && eslint . --fix",
+    "fmt": "pnpm run fix:fmt",
+    "gen": "run-s gen:index gen:readme",
+    "gen:index": "run-s gen:index:src fix:fmt",
+    "gen:index:src": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/gen-index-ts.mts ./src --index-ext .mts --export-ext .mjs --target-ext .mts",
+    "gen:readme": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/embed-examples.mts",
+    "test": "pnpm run check:test",
+    "watch:test": "pnpm run z:vitest",
+    "watch:types": "node ../../node_modules/typescript-native/bin/tsc --noEmit --watch -p ./tsconfig.json",
+    "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"
+  }
 }

package/src/bindings.mts

@@ -0,0 +1,62 @@
+import {
+  AST_NODE_TYPES,
+  ASTUtils,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types */
+
+/**
+ * Whether `name`, read at `node`, resolves to something this file writes down
+ * — a declaration, a parameter, an import — rather than to a global or a
+ * standard-library type of the same name.
+ *
+ * The scope manager makes an implicit variable for every reference it cannot
+ * resolve, so `findVariable` finds `Exclude` in a file that never declares it;
+ * only a variable with a definition was written in the file.
+ */
+export const isLocallyBound = (
+  sourceCode: TSESLint.SourceCode,
+  node: TSESTree.Node,
+  name: string,
+): boolean => {
+  const variable = ASTUtils.findVariable(sourceCode.getScope(node), name);
+
+  return variable !== null && variable.defs.length > 0;
+};
+
+/**
+ * Whether `name`, read at `node`, resolves to a binding that is not an import
+ * from `moduleName` — a declaration, a parameter, or an import from another
+ * module. A fix that makes code at `node` refer to `moduleName`'s export
+ * `name` has to give up then, because the name would refer to that binding
+ * instead.
+ *
+ * The innermost binding decides: an import from `moduleName` at the top of the
+ * file does not help a name a function shadows around `node`.
+ */
+export const hasForeignBinding = (
+  sourceCode: TSESLint.SourceCode,
+  node: TSESTree.Node,
+  name: string,
+  moduleName: string,
+): boolean => {
+  const variable = ASTUtils.findVariable(sourceCode.getScope(node), name);
+
+  return variable?.defs.some((def) => !isImportFrom(def, moduleName)) ?? false;
+};
+
+/**
+ * Whether `def` is a binding an `import … from '<moduleName>'` declaration
+ * introduces.
+ */
+const isImportFrom = (
+  def: TSESLint.Scope.Definition,
+  moduleName: string,
+): boolean =>
+  (def.node.type === AST_NODE_TYPES.ImportSpecifier ||
+    def.node.type === AST_NODE_TYPES.ImportDefaultSpecifier ||
+    def.node.type === AST_NODE_TYPES.ImportNamespaceSpecifier) &&
+  def.node.parent.type === AST_NODE_TYPES.ImportDeclaration &&
+  def.node.parent.source.value === moduleName;

package/src/imports.mts

@@ -0,0 +1,172 @@
+import {
+  AST_NODE_TYPES,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+import type { DeepReadonly } from 'ts-type-forge';
+import { isTypeWrapper, skipTypeWrappers } from './type-wrappers.mjs';
+
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types */
+
+/**
+ * Every `import … from '<moduleName>'` declaration in the file, not only the
+ * first: `import type { A } from 'm'` and `import { b } from 'm'` are two
+ * declarations, and a name imported by either is in scope.
+ */
+export const getImportDeclarations = (
+  program: TSESTree.Program,
+  moduleName: string,
+): readonly TSESTree.ImportDeclaration[] =>
+  program.body.filter(
+    (node): node is TSESTree.ImportDeclaration =>
+      node.type === AST_NODE_TYPES.ImportDeclaration &&
+      node.source.value === moduleName,
+  );
+
+/**
+ * The exported names `declarations` import by name, whatever they are bound to
+ * locally: `import { a, b as c }` gives `a` and `b`.
+ */
+export const getNamedImports = (
+  declarations: DeepReadonly<TSESTree.ImportDeclaration[]>,
+): readonly string[] =>
+  declarations.flatMap((declaration) =>
+    declaration.specifiers.flatMap((specifier) =>
+      specifier.type === AST_NODE_TYPES.ImportSpecifier
+        ? [importedNameOf(specifier)]
+        : [],
+    ),
+  );
+
+/**
+ * The local name `declarations` bind the export `importedName` to, or
+ * `undefined` when they do not import it: `'y'` for `import { x as y }`. A fix
+ * writes this rather than the exported name, which may not be in scope.
+ */
+export const getImportedLocalName = (
+  declarations: DeepReadonly<TSESTree.ImportDeclaration[]>,
+  importedName: string,
+): string | undefined =>
+  declarations
+    .flatMap((declaration) => declaration.specifiers)
+    .find(
+      (specifier) =>
+        specifier.type === AST_NODE_TYPES.ImportSpecifier &&
+        importedNameOf(specifier) === importedName,
+    )?.local.name;
+
+/** What {@link buildCalleeResolver}'s resolver says a callee calls. */
+export type ResolvedCallee = Readonly<{
+  /** The exported name, whatever the callee calls it locally. */
+  canonicalName: string;
+
+  /**
+   * The identifier to rewrite to change what is called: the callee itself for
+   * a named import, the property for a namespace import.
+   */
+  propertyNode: TSESTree.Identifier;
+
+  /** Whether the call goes through a namespace import (`m.f(...)`). */
+  isNamespace: boolean;
+}>;
+
+/**
+ * Builds a function that says which export of the module `declarations`
+ * import a callee calls, or `undefined` when it calls none of them. It knows
+ * named imports, aliased ones (`import { f as g }` → `g(...)` calls `f`) and
+ * namespace imports (`import * as m` → `m.f(...)`), and reads both the callee
+ * and a namespace object through their type wrappers:
+ * `(f as (u: unknown) => boolean)(x)` and `(m as typeof m).f(x)` still call
+ * `f`.
+ */
+export const buildCalleeResolver = (
+  declarations: DeepReadonly<TSESTree.ImportDeclaration[]>,
+): ((callee: TSESTree.Expression) => ResolvedCallee | undefined) => {
+  const specifiers = declarations.flatMap(
+    (declaration) => declaration.specifiers,
+  );
+
+  const namespaceNames: ReadonlySet<string> = new Set(
+    specifiers.flatMap((specifier) =>
+      specifier.type === AST_NODE_TYPES.ImportNamespaceSpecifier
+        ? [specifier.local.name]
+        : [],
+    ),
+  );
+
+  const localToCanonical: ReadonlyMap<string, string> = new Map(
+    specifiers.flatMap((specifier) =>
+      specifier.type === AST_NODE_TYPES.ImportSpecifier
+        ? [[specifier.local.name, importedNameOf(specifier)] as const]
+        : [],
+    ),
+  );
+
+  const resolve = (callee: TSESTree.Expression): ResolvedCallee | undefined => {
+    if (isTypeWrapper(callee)) {
+      return resolve(callee.expression);
+    }
+
+    if (callee.type === AST_NODE_TYPES.Identifier) {
+      const canonicalName = localToCanonical.get(callee.name);
+
+      return canonicalName === undefined
+        ? undefined
+        : { canonicalName, propertyNode: callee, isNamespace: false };
+    }
+
+    if (
+      callee.type !== AST_NODE_TYPES.MemberExpression ||
+      callee.computed ||
+      callee.property.type !== AST_NODE_TYPES.Identifier
+    ) {
+      return undefined;
+    }
+
+    const object = skipTypeWrappers(callee.object);
+
+    return object.type === AST_NODE_TYPES.Identifier &&
+      namespaceNames.has(object.name)
+      ? {
+          canonicalName: callee.property.name,
+          propertyNode: callee.property,
+          isNamespace: true,
+        }
+      : undefined;
+  };
+
+  return resolve;
+};
+
+/**
+ * A fix that inserts `import { <specifiers> } from '<moduleName>';` at the top
+ * of the file, or no fix when `specifiers` is empty. Each specifier is written
+ * as given, so `type T` imports a type.
+ *
+ * The placement is deliberately naive: an import sorter
+ * (prettier-plugin-organize-imports or any equivalent) merges and orders it
+ * afterwards. Put every name one report needs into a single call: ESLint
+ * merges the fixes of one report into one edit, and two fixes inserting at the
+ * start of the file conflict, so that one of them is dropped.
+ */
+export const buildNamedImportFix = (
+  fixer: TSESLint.RuleFixer,
+  program: TSESTree.Program,
+  moduleName: string,
+  specifiers: readonly string[],
+): readonly TSESLint.RuleFix[] =>
+  specifiers.length === 0
+    ? ([] as const)
+    : ([
+        fixer.insertTextBefore(
+          program,
+          `import { ${specifiers.join(', ')} } from '${moduleName}';\n`,
+        ),
+      ] as const);
+
+const importedNameOf = (
+  specifier: DeepReadonly<TSESTree.ImportSpecifier>,
+): string =>
+  specifier.imported.type === AST_NODE_TYPES.Identifier
+    ? specifier.imported.name
+    : specifier.imported.value;

package/src/index.mts

@@ -0,0 +1,4 @@
+export * from './bindings.mjs';
+export * from './imports.mjs';
+export * from './parentheses.mjs';
+export * from './type-wrappers.mjs';

package/src/parentheses.mts

@@ -0,0 +1,74 @@
+import {
+  AST_NODE_TYPES,
+  ASTUtils,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+import type { DeepReadonly } from 'ts-type-forge';
+
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types */
+
+/**
+ * How many pairs of parentheses the source puts around `node`: `0` for `a`, `2`
+ * for `((a))`. The parentheses of a call's argument list are not counted.
+ */
+export const parenthesesDepth = (
+  sourceCode: TSESLint.SourceCode,
+  node: DeepReadonly<TSESTree.Node>,
+): number => {
+  const mutableNode = asNode(node);
+
+  const depthFrom = (known: number): number =>
+    ASTUtils.isParenthesized(known + 1, mutableNode, sourceCode)
+      ? depthFrom(known + 1)
+      : known;
+
+  return depthFrom(0);
+};
+
+/**
+ * The range of `node` together with the parentheses the source puts around it,
+ * which `node.range` leaves out: all of `((Array.isArray))` for the member
+ * expression inside.
+ */
+export const getRangeWithParens = (
+  sourceCode: TSESLint.SourceCode,
+  node: DeepReadonly<TSESTree.Node>,
+): TSESTree.Range => {
+  const depth = parenthesesDepth(sourceCode, node);
+
+  if (depth === 0) {
+    return [node.range[0], node.range[1]];
+  }
+
+  const opening = sourceCode.getTokenBefore(asNode(node), { skip: depth - 1 });
+
+  const closing = sourceCode.getTokenAfter(asNode(node), { skip: depth - 1 });
+
+  return opening === null || closing === null
+    ? [node.range[0], node.range[1]]
+    : [opening.range[0], closing.range[1]];
+};
+
+/**
+ * The source text of `node` to put in a call's argument list. A node's text
+ * never includes the parentheses the source wrote around it, so a sequence
+ * expression gets them back here, whether or not the source had them:
+ * `(setup(), x)` would otherwise become two arguments.
+ */
+export const getArgumentText = (
+  sourceCode: TSESLint.SourceCode,
+  node: DeepReadonly<TSESTree.Node>,
+): string => {
+  const text = sourceCode.text.slice(node.range[0], node.range[1]);
+
+  return node.type === AST_NODE_TYPES.SequenceExpression ? `(${text})` : text;
+};
+
+/**
+ * The parser's node, which the token store takes as mutable, for one that this
+ * package only reads.
+ */
+const asNode = (node: DeepReadonly<TSESTree.Node>): TSESTree.Node =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  node as TSESTree.Node;

package/src/type-wrappers.mts

@@ -0,0 +1,73 @@
+import { AST_NODE_TYPES, type TSESTree } from '@typescript-eslint/utils';
+import type { DeepReadonly, RelaxedExtract } from 'ts-type-forge';
+
+/**
+ * The four expressions that change a value's type and nothing else: `x as T`,
+ * `x!`, `x satisfies T` and `<T>x`.
+ */
+export type TypeWrapper =
+  | TSESTree.TSAsExpression
+  | TSESTree.TSNonNullExpression
+  | TSESTree.TSSatisfiesExpression
+  | TSESTree.TSTypeAssertion;
+
+/**
+ * The expression a type wrapper among `N` wraps, as mutable or as readonly as
+ * `N` itself: `TSESTree.Expression` for a mutable node,
+ * `DeepReadonly<TSESTree.Expression>` for a readonly one, and `never` when no
+ * member of `N` is a type wrapper.
+ */
+export type WrappedExpression<N> = RelaxedExtract<
+  N,
+  DeepReadonly<TypeWrapper> | TypeWrapper
+>['expression'];
+
+/**
+ * Whether `node` is a type wrapper (see {@link TypeWrapper}). Takes a readonly
+ * or a mutable node and narrows it without changing which.
+ */
+export const isTypeWrapper = (
+  node: DeepReadonly<TSESTree.Node>,
+): node is DeepReadonly<TypeWrapper> | TypeWrapper =>
+  TYPE_WRAPPERS.has(node.type);
+
+/**
+ * `node` with every `as`, `satisfies`, `!` and `<T>` around it taken off: the
+ * expression whose value it is. A wrapper changes no value, so a rule judges
+ * syntax on what this returns — `xs.length > (0 as number)` compares with the
+ * literal `0`, and `(Number satisfies NumberConstructor)('1')` calls `Number` —
+ * and writes its fix from the original node, so that the wrapper is kept. A
+ * type is another matter: see {@link typeWrapperLayers}.
+ */
+export const skipTypeWrappers = <N extends DeepReadonly<TSESTree.Node>>(
+  node: N,
+): N | WrappedExpression<N> =>
+  isTypeWrapper(node) ? skipTypeWrappers(node.expression) : node;
+
+/**
+ * `node` and every expression inside the type wrappers around it, outermost
+ * first: `x as A as B` gives `x as A as B`, `x as A` and `x`, the last of which
+ * is `skipTypeWrappers(node)`.
+ *
+ * A conclusion a rule draws from a type — that a guard always holds, that a
+ * value is an array, that an operation may throw — has to hold for the type of
+ * every layer. An assertion therefore only ever makes a rule more cautious:
+ * one that widens (`x as string | null`) is the author saying the value may be
+ * `null`, and is respected; one that narrows (`x!`, `v as string` on an
+ * `unknown`) is a claim the checker cannot verify, and the value's own type
+ * still decides. The fix, which keeps the wrapper, has to type-check at every
+ * layer too.
+ */
+export const typeWrapperLayers = <N extends DeepReadonly<TSESTree.Node>>(
+  node: N,
+): readonly (N | WrappedExpression<N>)[] =>
+  isTypeWrapper(node)
+    ? ([node, ...typeWrapperLayers(node.expression)] as const)
+    : ([node] as const);
+
+const TYPE_WRAPPERS: ReadonlySet<AST_NODE_TYPES> = new Set([
+  AST_NODE_TYPES.TSAsExpression,
+  AST_NODE_TYPES.TSNonNullExpression,
+  AST_NODE_TYPES.TSSatisfiesExpression,
+  AST_NODE_TYPES.TSTypeAssertion,
+]);