import * as ESTree from "estree";
|
import { Server } from "../tern";
|
export { };
|
|
// #### Context ####
|
interface ContextConstructor {
|
new(defs: any[], parent: Server): Context;
|
}
|
export const Context: ContextConstructor;
|
export interface Context {
|
parent?: Server | undefined;
|
topScope: Scope;
|
/** The primitive number type. */
|
num: Prim & { name: "number" };
|
/** The primitive string type. */
|
str: Prim & { name: "string" };
|
/** The primitive boolean type. */
|
bool: Prim & { name: "bool" };
|
}
|
/** Returns the current context object. */
|
export function cx(): Context;
|
/** Calls f with the current context bound to context. Basically, all code that does something with the inference engine should be wrapped in such a call. */
|
export function withContext<R>(context: Context, f: () => R): R;
|
|
// #### Analysis ####
|
/** Parse a piece of code for use by Tern. Will automatically fall back to the error-tolerant parser if the regular parser can’t parse the code. */
|
export function parse(text: string, options?: {}): ESTree.Program;
|
/**
|
* Analyze a syntax tree. `name` will be used to set the origin of types, properties, and variables produced by this code.
|
* The optional `scope` argument can be used to specify a scope in which the code should be analyzed.
|
* It will default to the top-level scope.
|
*/
|
export function analyze(ast: ESTree.Program, name: string, scope?: Scope): void;
|
/**
|
* Purges the types that have one of the origins given from the context. `start` and `end` can be given to only purge
|
* types that occurred in the source code between those offsets. This is not entirely precise — the state of the
|
* context won’t be back where it was before the file was analyzed — but it prevents most of the
|
* noticeable inaccuracies that re-analysis tends to produce.
|
*/
|
export function purgeTypes(origins: string[], start?: number, end?: number): void;
|
/**
|
* Cleaning up variables is slightly trickier than cleaning up types. This does a first pass over the given scope,
|
* and marks variables defined by the given origins. This is indended to be followed by a call to `analyze` and then a call to `purgeMarkedVariables`.
|
*/
|
export function markVariablesDefinedBy(scope: Scope, origins: string[], start?: number, end?: number): void;
|
/** Purges variables that were marked by a call to markVariablesDefinedBy and not re-defined in the meantime. */
|
export function purgeMarkedVariables(): void;
|
|
// #### Types ####
|
interface ObjConstructor {
|
new(proto: object | true | null, name?: string): Obj;
|
}
|
/** Constructor for the type that represents JavaScript objects. `proto` may be another object, or `true` as a short-hand for `Object.prototype`, or `null` for prototype-less objects. */
|
export const Obj: ObjConstructor;
|
export interface Obj extends IType {
|
/** The name of the type, if any. */
|
name: string | undefined;
|
/** The prototype of the object, or null. */
|
proto: (Obj & { name: string }) | null;
|
/** An object mapping the object’s known properties to AVals. Don’t manipulate this directly (ever), only use it if you have to iterate over the properties. */
|
props: Readonly<{
|
[key: string]: AVal;
|
}>;
|
/** Looks up the AVal associated with the given property, or returns null if it doesn’t exist. */
|
hasProp(prop: string): AVal | null;
|
/** Looks up the given property, or defines it if it did not yet exist (in which case it will be associated with the given AST node). */
|
defProp(prop: string, originNode?: ESTree.Node): AVal;
|
/**
|
* Asks the AVal if it contains an Object type. Useful when
|
* you aren’t interested in other kinds of types.
|
*/
|
getObjType(): Obj;
|
getType(): Obj;
|
/** Get an `AVal` that represents the named property of this type. */
|
getProp(prop: string): AVal;
|
/** Call the given function for all properties of the object, including properties that are added in the future. */
|
forAllProps(f: (prop: string, val: AVal, local: boolean) => void): void;
|
gatherProperties(f: (...args: any[]) => void, depth: number): void;
|
}
|
|
interface FnConstructor {
|
new(name: string | undefined, self: AVal, args: AVal[], argNames: string[], retval: AVal): Fn;
|
}
|
/** Constructor for the type that implements functions. Inherits from `Obj`. The `AVal` types are used to track the input and output types of the function. */
|
export const Fn: FnConstructor;
|
export interface Fn extends Obj {
|
readonly args?: AVal[] | undefined;
|
readonly argNames?: string[] | undefined;
|
self?: Type | undefined;
|
readonly retval: AVal;
|
/**
|
* Asks the AVal if it contains a function type. Useful when
|
* you aren’t interested in other kinds of types.
|
*/
|
getFunctionType(): Fn;
|
isArrowFn(): boolean;
|
getType(): Fn;
|
}
|
|
interface PrimConstructor {
|
new(proto: object | null, name?: string): Prim;
|
}
|
export const Prim: PrimConstructor;
|
export interface Prim extends IType {
|
/** The name of the type, if any. */
|
name: "string" | "bool" | "number";
|
/** The prototype of the object, or null. */
|
proto: Obj & { name: string };
|
/** Get an `AVal` that represents the named property of this type. */
|
getProp(prop: string): AVal;
|
getType(): Prim;
|
gatherProperties(f: (...args: any[]) => void, depth: number): void;
|
}
|
|
interface ArrConstructor {
|
/** Constructor that creates an array type with the given content type. */
|
new(contentType?: AVal): Arr;
|
}
|
export const Arr: ArrConstructor;
|
export interface Arr extends Obj {
|
name: "Array";
|
getType(): Arr;
|
}
|
interface TypeConstructor {
|
new(): Type;
|
}
|
export const Type: TypeConstructor;
|
export type Type = Obj | Prim;
|
|
// tslint:disable-next-line: interface-name
|
export interface IType extends ANull {
|
/** The origin file of the type. */
|
origin: string;
|
/**
|
* The syntax node that defined the type. Only present for object and function types,
|
* and even for those it may be missing (if the type was created by a type definition file,
|
* or synthesized in some other way).
|
*/
|
originNode?: ESTree.Node | undefined;
|
/** Return a string that describes the type. maxDepth indicates the depth to which inner types should be shown. */
|
toString(maxDepth: number): string;
|
/** Queries whether the AVal _currently_ holds the given type. */
|
hasType(type: Type): boolean;
|
getType(): Type;
|
}
|
|
// #### Abstract Values ####
|
|
interface AValConstructor {
|
new(): AVal;
|
}
|
export const AVal: AValConstructor;
|
|
/**
|
* Abstract values are objects used to represent sets of types. Each variable
|
* and property has an abstract value associated with it, but they are also
|
* used for other purposes, such as tracking the return type of a function,
|
* or building up the type for some kinds of expressions.
|
*
|
* In a cleanly typed program where each thing has only a single type,
|
* abstract values will all have one type associated with them. When,
|
* for example, a variable can hold two different types of values,
|
* the associated abstract value will hold both these types. In some cases,
|
* no type can be assigned to something at all,
|
* in which case the abstract value remains empty.
|
*/
|
export interface AVal extends ANull {
|
/**
|
* Add a type to this abstract value. If the type is already in there,
|
* this is a no-op. weight can be given to give this type a non-default
|
* weight, which is mostly useful when adding a provisionary type that
|
* should be overridden later if a real type is found. The default weight
|
* is 100, and passing a weight lower than that will make the type
|
* assignment “weak”.
|
*/
|
addType(type: Type, weight?: number): void;
|
/**
|
* Sets this AVal to propagate all types it receives to the given
|
* constraint. This is the mechanism by which types are propagated
|
* through the type graph.
|
*/
|
propagate(target: Constraint): void;
|
/** Queries whether the AVal _currently_ holds the given type. */
|
hasType(type: Type): boolean;
|
/** Queries whether the AVal is empty. */
|
isEmpty(): boolean;
|
/**
|
* Asks the abstract value for its current type. May return `null`
|
* when there is no type, or conflicting types are present. When
|
* `guess` is true or not given, an empty AVal will try to use
|
* heuristics based on its propagation edges to guess a type.
|
*/
|
getType(guess?: boolean): Type | null;
|
/**
|
* Asks the AVal if it contains a function type. Useful when
|
* you aren’t interested in other kinds of types.
|
*/
|
getFunctionType(): Fn | undefined;
|
/** Get an `AVal` that represents the named property of this type. */
|
getProp(prop: string): AVal;
|
/** Call the given function for all properties of the object, including properties that are added in the future. */
|
forAllProps(f: (prop: string, val: AVal, local: boolean) => void): void;
|
/**
|
* Asks the AVal if it contains an Object type. Useful when
|
* you aren’t interested in other kinds of types.
|
*/
|
getObjType(): Obj | null;
|
/**
|
* Abstract values that are used to represent variables
|
* or properties will have, when possible, an `originNode`
|
* property pointing to an AST node.
|
*/
|
gatherProperties(f: (...args: any[]) => void, depth: number): void;
|
originNode?: ESTree.Node | undefined;
|
/** An object mapping the object’s known properties to AVals. Don’t manipulate this directly (ever), only use it if you have to iterate over the properties. */
|
props: Partial<Readonly<{
|
[key: string]: AVal;
|
}>>;
|
readonly types: Type[];
|
readonly propertyOf?: Obj | undefined;
|
}
|
|
/**
|
* A variant of AVal used for unknown, dead-end values. Also serves
|
* a prototype for AVals, Types, and Constraints because it
|
* implements 'empty' versions of all the methods that the code expects.
|
*/
|
export const ANull: ANull;
|
export interface ANull {
|
addType(...args: any[]): void;
|
propagate(...args: any[]): void;
|
getProp(...args: any[]): ANull;
|
forAllProps(...args: any[]): void;
|
hasType(...args: any[]): boolean;
|
isEmpty(...args: any[]): boolean;
|
getFunctionType(...args: any[]): ANull | undefined;
|
getObjType(...args: any[]): ANull | undefined | null;
|
getSymbolType(...args: any[]): ANull | undefined;
|
getType(...args: any[]): ANull | undefined | null;
|
gatherProperties(...args: any[]): void;
|
propagatesTo(): any;
|
typeHint(...args: any[]): ANull | undefined | null;
|
propHint(...args: any[]): string | undefined;
|
toString(...args: any[]): string;
|
}
|
|
// #### Constraints ####
|
interface ConstraintConstructor {
|
new(methods: { [key: string]: any }): { new(): Constraint };
|
}
|
/**
|
* This is a constructor-constructor for constraints. It’ll create a
|
* constructor with all the given methods copied into its prototype,
|
* which will run its construct method on its arguments when instantiated.
|
*/
|
export const constraint: ConstraintConstructor;
|
export interface Constraint extends ANull {
|
/** May return a type that `getType` can use to “guess” its type based on the fact that it propagates to this constraint. */
|
typeHint(): Type | undefined;
|
/** May return a string when this constraint is indicative of the presence of a specific property in the source AVal. */
|
propHint(): string | undefined;
|
}
|
|
// #### Scopes ####
|
interface ScopeConstructor {
|
new(): Scope;
|
new(parent: Scope, originNode: ESTree.Node): Scope;
|
}
|
export const Scope: ScopeConstructor;
|
export interface Scope extends Obj {
|
/**
|
* Ensures that this scope or some scope above it has a property by the given name
|
* (defining it in the top scope if it is missing), and, if the property doesn’t
|
* already have an `originNode`, assigns the given node to it.
|
*/
|
defVar(name: string, originNode: ESTree.Node): AVal;
|
}
|
|
// #### Utilities ####
|
/**
|
* Searches the given syntax tree for an expression that ends at the given `end` offset and,
|
* if `start` is given, starts at the given start offset. `scope` can be given to override the
|
* outer scope, which defaults to the context’s top scope. Will return a `{node, state}`
|
* object if successful, where `node` is AST node, and `state` is the scope at that point.
|
* Returns `null` if unsuccessful.
|
*/
|
export function findExpressionAt(ast: ESTree.Program, start: number | undefined, end: number, scope?: Scope): { node: ESTree.Node, state: Scope } | null;
|
/**
|
* Similar to `findExpressionAt`, except that it will return the innermost expression
|
* node that spans the given range, rather than only exact matches.
|
*/
|
export function findExpressionAround(ast: ESTree.Program, start: number | undefined, end: number, scope?: Scope): { node: ESTree.Node, state: Scope } | null;
|
/** Similar to `findExpressionAround`, except that it use the same AST walker as `findExpressionAt`. */
|
export function findClosestExpression(ast: ESTree.Program, start: number | undefined, end: number, scope?: Scope): { node: ESTree.Node, state: Scope } | null;
|
/** Determine an expression for the given node and scope (as returned by the functions above). Will return an `AVal` or plain `Type`. */
|
export function expressionType(expr: { node: ESTree.Node, state: Scope | null }): AVal | Type;
|
/** Find the scope at a given position in the syntax tree. The `scope` parameter can be used to override the scope used for code that isn’t wrapped in any function. */
|
export function scopeAt(ast: ESTree.Program, pos: number, scope?: Scope): Scope;
|
/**
|
* Will traverse the given syntax tree, using `scope` as the starting scope, looking for references to variable `name` that
|
* resolve to scope `refScope`, and call `f` with the node of the reference and its local scope for each of them.
|
*/
|
export function findRefs(ast: ESTree.Program, scope: Scope, name: string, refScope: Scope, f: (Node: ESTree.Node, Scope: Scope) => void): void;
|
/**
|
* Analogous to `findRefs`, but used to look for references to a specific property instead. Whereas `findRefs`
|
* is precise, this is dependent on type inference, and thus can not be relied on to be precise.
|
*/
|
export function findPropRefs(ast: ESTree.Program, scope: Scope, objType: Obj, propName: string, f: (Node: ESTree.Node) => void): void;
|
/** Whenever infer guesses a type through fuzzy heuristics (through `getType` or `expressionType`), it sets a flag. `didGuess` tests whether the guessing flag is set. */
|
export function didGuess(): boolean;
|
/** Whenever infer guesses a type through fuzzy heuristics (through `getType` or `expressionType`), it sets a flag. `resetGuessing` resets the guessing flag. */
|
export function resetGuessing(val?: boolean): void;
|
