@aoelite/refpact-ts 0.0.0-stage → 0.1.2

package/dist/frontend/imports.d.ts

@@ -0,0 +1,149 @@
+import type { Node, SourceFile } from "./compiler.ts";
+import type { DependencyKind } from "./dependencies.ts";
+/** The reference kinds of the TypeScript front end. */
+export declare const KINDS: readonly ["import", "import-type", "dynamic-import", "require", "export-from", "export-type-from", "resolve", "global"];
+/**
+ * The kind of a place that asks where a module is and does not load it: `require.resolve("m")`,
+ * `import.meta.resolve("m")` and `new URL("./m", import.meta.url)`.
+ */
+export declare const RESOLVE_KIND: Kind;
+/**
+ * The kind of a use of a global of the host, such as `process.env` or `fetch(..)`: a name
+ * that no file of the project declares and that the ECMAScript library does not declare.
+ */
+export declare const GLOBAL_KIND: Kind;
+/**
+ * The kind of a use of a member of a class, an interface or an enum: `order.total`. Only a
+ * project that is loaded with `resolveMembers` has this kind.
+ */
+export declare const MEMBER_KIND: Kind;
+/** One of the reference kinds of the TypeScript front end. */
+export type Kind = (typeof KINDS)[number] | "member" | DependencyKind;
+/** One name taken from a module: `a` in `import { a as b } from "m"`. */
+export interface NameUse {
+    /** The name as the module exports it. `default` for a default import. */
+    readonly exported: string;
+    readonly kind: Kind;
+    /** The node that carries the position and the symbol. */
+    readonly node: Node;
+    /**
+     * True for a name in the braces of an `import` or an `export ... from`. The symbol of such
+     * a name is an alias of the export that the module has under `exported`.
+     */
+    readonly specifier?: true;
+}
+/** A local name that stands for a whole module: `ns` in `import * as ns from "m"`. */
+export interface NamespaceBinding {
+    readonly local: string;
+    readonly node: Node;
+    readonly kind: Kind;
+}
+/** One statement or expression that names a module. */
+export interface ModuleUse {
+    readonly specifier: string;
+    readonly specifierNode: Node;
+    /** The node whose position is reported for a use of the module as a whole. */
+    readonly at: Node;
+    readonly kind: Kind;
+    /** True when the construct uses the module as a whole and not only some names of it. */
+    readonly whole: boolean;
+    readonly names: readonly NameUse[];
+    readonly namespace?: NamespaceBinding;
+    /** The `require` identifier of a `require("m")` call. It may be a local name, not Node's. */
+    readonly requireNode?: Node;
+    /**
+     * How the code gives the specifier, when it is not one string in the place.
+     * - `constant`: the code computes it from strings that are known, and `specifier` is the result.
+     * - `pattern`: a part is not known. `specifier` has a `*` for each such part.
+     * - `glob`: the argument of `import.meta.glob`, which is a glob pattern.
+     * - `unknown`: nothing of it is known. `specifier` is empty.
+     */
+    readonly computed?: "constant" | "pattern" | "glob" | "unknown";
+    /**
+     * The names of constants that the specifier is computed from, each with the name of the
+     * declaration that was read. The value holds only when the compiler says that both are
+     * one variable.
+     */
+    readonly constants?: readonly {
+        readonly use: Node;
+        readonly declaration: Node;
+    }[];
+    /** True for `new URL(..)`, which may name a file that is no module, such as an image. */
+    readonly asset?: true;
+}
+/** `object.member` or `object.member` in a type, where `object` may be a namespace binding. */
+export interface MemberUse {
+    readonly object: Node;
+    readonly member: Node;
+    readonly objectName: string;
+    readonly memberName: string;
+    /**
+     * For a member of a `const` that stands for a namespace binding, `const f = ns; f.name`: the
+     * name of the declaration of the `const`, and the name of the binding in its value.
+     * `object` is then the `const` where it is used, and `objectName` is the name of the binding.
+     */
+    readonly alias?: {
+        readonly declaration: Node;
+        readonly of: Node;
+    };
+}
+/**
+ * Finds every construct of the file that names a module.
+ *
+ * `prune` lets the visit leave out nodes, see {@link Mentions}. It must be `false` for a
+ * JavaScript file: the compiler makes nodes from the types in JSDoc comments, and such a node
+ * is in the text before the node that it belongs to, not in it.
+ */
+export declare function collectModuleUses(sourceFile: SourceFile, prune: boolean): ModuleUse[];
+/** Finds `object.member` where `object` is one of the given local names. */
+export declare function collectMemberUses(sourceFile: SourceFile, locals: ReadonlySet<string>, prune: boolean): MemberUse[];
+/**
+ * The names after the dot of each `object.name` of a file, in the order of the text. What a
+ * name is a member of depends on the type of the object, which only the compiler knows.
+ * Every node of the file is visited.
+ */
+export declare function collectAccesses(sourceFile: SourceFile): Node[];
+/**
+ * A name in a file that may be a global: `fetch` in `fetch(..)`, or `process` and its member
+ * `env` in `process.env`. Through `globalThis`, `window`, `self` and `global`, the global is
+ * the name after the dot: `window.localStorage` is `localStorage`. Only the compiler can tell
+ * whether the names are globals: `node` and `through` are the nodes to ask.
+ */
+export interface GlobalUse {
+    /** The node that carries the position. */
+    readonly at: Node;
+    /** The node of the name of the global. */
+    readonly node: Node;
+    /** The name of the global. */
+    readonly name: string;
+    /** The member of the global that is used, if any: `env` in `process.env`. */
+    readonly member?: string;
+    /** `globalThis`, `window`, `self` or `global`, when the global is written as its member. */
+    readonly through?: Node;
+    /** The shorthand property that the name is, `{ fetch }`: the compiler is asked for its value apart. */
+    readonly shorthand?: Node;
+}
+/**
+ * The names in value positions that may be globals, in the order of the text. Types,
+ * the names after a dot, JSX tags and the callee of `require(..)` are left out.
+ */
+export declare function collectGlobalUses(sourceFile: SourceFile): GlobalUse[];
+/**
+ * The markers that a file can contain: a use of the global `console`, a `debugger`
+ * statement, and `unresolved-import`, an import of a relative path, a `paths` alias or a
+ * `#name` of `imports` that leads to no file.
+ */
+export declare const MARKERS: readonly ["console", "debugger", "unresolved-import", "computed-import"];
+/** One of {@link MARKERS}. */
+export type MarkerName = (typeof MARKERS)[number];
+/**
+ * A place that may be a marker. A `debugger` statement is one. `console.name` is one when
+ * `console` is the global, which only the compiler can tell: `object` is the node to ask.
+ */
+export interface MarkerUse {
+    readonly marker: MarkerName;
+    readonly at: Node;
+    readonly object?: Node;
+}
+/** The `debugger` statements of a file, and its `console.name`, in the order of the text. */
+export declare function collectMarkers(sourceFile: SourceFile, prune: boolean): MarkerUse[];