eslint-rule-forge 0.0.0-stage → 0.2.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,212 @@
-# 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.
+
+## Negation
+
+Writing the negation of a condition the short way, as a fix that removes a
+ternary or turns a filter into a loop has to.
+
+| Helper                        | What it gives                                                                                                             |
+| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------ |
+| `negationOf`                  | `a !== b` for `a === b`, `!a && !b` for `a \|\| b`, `a` for `!a` (when a boolean), else `!a`; parenthesized as an operand |
+| `prefixedNegationOf`          | `!a`, `!f(x)`, `!(a === b)`: a `!` in front, with parentheses only when it needs them                                     |
+| `isComparison`                | whether a node is an equality or a relational comparison                                                                  |
+| `isExactlyInvertible`         | whether inverting a comparison's operator is its exact negation: always for an equality, for `<` only without `NaN`       |
+| `invertedComparisonText`      | the comparison's source with its operator inverted                                                                        |
+| `needsParenthesesAsOperandOf` | whether a node needs parentheses as an operand of `&&` or `\|\|`                                                          |
+| `createGetLayerTypes`         | a function giving a node's type at every type-wrapper layer, which the checks above ask                                   |
+
+`negationOf` gives `undefined` when the only exact negation is `!!a` (for an
+`a` that may not be a boolean) or `!(a < b)` (for operands that may be `NaN`),
+so that a rule can choose between `prefixedNegationOf` and giving up. Where
+only the truthiness of the negation is read, such as the test of an `if`, its
+context may call every node a boolean.
+
+## 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":"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"}

package/dist/index.d.mts

@@ -0,0 +1,6 @@
+export * from './bindings.mjs';
+export * from './imports.mjs';
+export * from './negation.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,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC"}

package/dist/index.mjs

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