circle-ir 4.15.0 → 4.16.0

package/dist/navigation/navigation-index.d.ts

@@ -28,9 +28,24 @@
  * repository, of which 7,246 are correctly unanswered (the target is outside
  * the tree) and 455 are these.
  *
- * What it deliberately does **not** do: invent a receiver type. Where no type
- * is known the answer is `inferred` or there is no answer, and `inferred` is a
- * permanent floor — see `Tier`.
+ * Two more, found by asking for the callers of overloaded and of overridden
+ * methods in a 6,900-file Java repository, where every such answer was wrong:
+ *
+ *   - **Overloads.** A call binds to one overload, chosen the way the compiler
+ *     chooses — by arity, then by argument types in the compiler's three
+ *     phases, then the most specific — and only where the types read off the
+ *     source make the choice certain. Where they do not, the site is
+ *     `unresolved` with `overload-ambiguous` and the candidates. A symbol may
+ *     carry a parameter list to ask about one overload; a query without one
+ *     on an overloaded method gets its answers grouped per overload.
+ *   - **Dispatch.** A call through a supertype's declaration can land on an
+ *     override, and a call to an override is a caller of the operation it
+ *     overrides. Both are answered `polymorphic`, with `via` naming what the
+ *     site binds to, and the query's `scope` says what dispatch it cannot see.
+ *
+ * What it deliberately does **not** do: invent a receiver type, or an
+ * argument type. Where no type is known the answer is `inferred`, ambiguous,
+ * or absent, and `inferred` is a permanent floor — see `Tier`.
  */
 import type { CircleIR, SupportedLanguage } from '../types/index.js';
 import type { NavigationAnswer, Query, QueryKind, QueryOptions } from './types.js';
@@ -77,6 +92,10 @@ export declare class NavigationIndex {
     private readonly parseMs;
     /** Direct subtypes, by supertype FQN. */
     private readonly subtypes;
+    /** A call's binding, once made. The index is immutable, so it never goes stale. */
+    private readonly bindings;
+    /** Calls by `line:column`, per file, built on first use. */
+    private readonly callsAt;
     constructor(input: NavigationFile[], options: BuildOptions);
     /**
      * Every call site that calls `symbol`, with how each was bound, plus every
@@ -86,6 +105,10 @@ export declare class NavigationIndex {
      * reported 147 callers of one method where the right answer was 0 `exact`,
      * 69 unverified and 78 contradicted by the resolver's own receiver type. Here
      * the 78 do not appear as answers at all, and the 69 arrive labelled.
+     *
+     * An overloaded method is answered per overload: with a parameter list in
+     * the symbol, for that overload alone; without one, for every overload,
+     * grouped and labelled, with a `note` saying so.
      */
     resolveCallers(query: Query, opts?: QueryOptions): NavigationAnswer;
     /** Every call made from inside `symbol`'s body, bound the same way. */
@@ -100,19 +123,28 @@ export declare class NavigationIndex {
      *
      * For `callers` the symbol is the call's own target — "who else calls what
      * this line calls". For `callees` it is the method whose body holds the
-     * line — "what does the method I am looking at call". Returns nothing when
-     * the site names no call, when the call cannot be bound to a target, or
-     * when the name is written twice on one line, which the key cannot separate.
+     * line — "what does the method I am looking at call". Either carries a
+     * parameter list when the name is overloaded, so the follow-up query asks
+     * about that overload alone. Returns nothing when the site names no call,
+     * when the call cannot be bound to one target, or when the name is written
+     * twice on one line, which the key cannot separate.
      */
     symbolAt(file: string, line: number, methodName: string, kind: QueryKind): string | undefined;
+    /** `bindCall`, reduced to what callers outside the query paths need. */
+    private symbolOfCall;
     /**
-     * Bind one call site to a target, or to nothing.
+     * Bind one call site to a target, to several candidates, or to nothing.
      *
      * The order matters and is the whole contract: a receiver type is sought
      * first, and only when none can be had does a name-only bind happen, which
-     * is labelled `inferred` and never anything better.
+     * is labelled `inferred` and never anything better. Within the type the
+     * receiver names, the overload is chosen by `selectOverload`, and a choice
+     * it cannot make is `ambiguous`, not a pick.
      */
-    private bind;
+    private bindCall;
+    private bindUncached;
+    /** Bind `call` to a member of `fqn` or of a supertype of it, choosing the overload. */
+    private bindInType;
     /**
      * The tier for a target, once the declaring type is known.
      *
@@ -126,8 +158,88 @@ export declare class NavigationIndex {
      * static resolver answers; only the tier changes.
      */
     private tierFor;
-    /** `new Widget()` → `app.Widget.<init>`. */
-    private asConstructor;
+    /** `new Widget()` → `app.Widget.<init>`, with the constructor chosen like any overload. */
+    private bindConstructor;
+    /**
+     * The overloads of `name` a receiver of type `fqn` can see: its own, then
+     * its supertypes', nearest first, leaving out any a nearer type overrides.
+     */
+    private visibleOverloads;
+    /** The declarations of `name` on `t` itself. `<init>` is its constructors. */
+    private declaredOverloads;
+    /**
+     * Choose the overload a call invokes, the way the compiler does — or say
+     * that the types read off the source do not decide it.
+     *
+     * Arity first. Then the compiler's three phases: without boxing or
+     * varargs, with boxing, with varargs. In the first phase that has any
+     * applicable overload, the most specific one wins. Every argument type here
+     * is a lower bound on what is known — an argument that cannot be typed fits
+     * anything — so the rule is applied only where it is sound: an overload is
+     * picked when it is **certainly** applicable and more specific than every
+     * overload that **might** be. Anything less is `ambiguous`.
+     */
+    private selectOverload;
+    /** Whether `c` applies to arguments of these types in compiler phase 1, 2 or 3. */
+    private applicable;
+    /** `m` is more specific than `o`: each of its parameter types fits the other's. */
+    private moreSpecific;
+    /**
+     * Whether a value of type `a` can be passed as `p` — certainly, possibly,
+     * or certainly not. `a === null` is an argument that could not be typed.
+     */
+    private fits;
+    /** Reference to reference: subtyping, as far as the tree and the JDK table know it. */
+    private refFits;
+    /** Is `t` certainly a type outside this tree? */
+    private isKnownForeignRef;
+    /** Is `t` a type declared in this tree? */
+    private isProjectRef;
+    /** Every supertype of a project type, split into what the tree holds and what it does not. */
+    private supertypesOf;
+    /** A type name that certainly names something outside the tree. */
+    private isKnownForeign;
+    /**
+     * The static type of one argument, or `null` when it cannot be known. The
+     * extractor types what the syntax and the declarations in scope say; an
+     * argument that is itself a call is typed here by binding that call and
+     * reading the chosen overload's return type.
+     */
+    private argumentType;
+    /**
+     * The type a generated `getX()` / `isX()` returns on `fqn`: the written
+     * type of field `x`, with the type that declares the field.
+     */
+    private generatedGetterType;
+    /**
+     * A member's written type as seen from a receiver of type `from`: a type
+     * parameter of the declaring type is replaced by the argument the
+     * superclass chain from `from` up to it supplies — `Loan extends
+     * Base<Long>` makes `Base<T>.getId()`'s `T` a `Long`. Returns the text and
+     * the file it must be resolved in, or nothing when a type parameter is
+     * left unbound.
+     */
+    private substitute;
+    /** The outermost call named `name` that starts at `line:column` in `rec`. */
+    private callAt;
+    /** A written type, resolved from one file's point of view. */
+    private typeRef;
+    /** Whether overload `o` of `owner` is what a query's parameter list names. */
+    private signatureMatches;
+    /** Same name and same erased parameter types: one overrides the other. */
+    private sameErasure;
+    /**
+     * How a site bound to `owner.overload` reaches `target`'s overload, if it
+     * does: through a supertype's declaration the target overrides, or by
+     * calling an override of the target.
+     */
+    private dispatchRelation;
+    /** Whether calls to `o` on `t` can dispatch anywhere but `t`'s own body. */
+    private dispatchIsOpen;
+    /** `a` is `b` or a subtype of it, by the edges the tree holds. */
+    private isSubtype;
+    /** The query's scope, with what dispatch it cannot see said out loud. */
+    private dispatchScope;
     /**
      * The receiver's static type, where it can be had without inventing one.
      *
@@ -143,14 +255,22 @@ export declare class NavigationIndex {
      * `Builder.of().step("a")` is typed by resolving `Builder`, then taking
      * `of`'s declared return type, then `step`'s. A step whose return type is
      * unknown ends the walk and the whole expression is untyped — a half-walked
-     * chain is not a type.
+     * chain is not a type. So does a step whose overloads of that arity
+     * disagree on what they return.
      */
     private typeOfExpression;
+    /**
+     * The return type of `name` called with `argc` arguments on `fqn`, when
+     * every overload of that arity agrees on it.
+     */
+    private returnTypeAt;
     /** The owner named by a static import of this call's method. */
     private staticOwnerFor;
     private enclosingTypeOf;
     /** The innermost declared type whose line range holds `line`. */
     private enclosingTypeAt;
+    /** The method whose body holds `line`, with a parameter list when its name is overloaded. */
+    private methodAt;
     /** Find `method` on `fqn` or on a supertype of it, inside the tree. */
     private lookupThroughHierarchy;
     /**
@@ -169,8 +289,8 @@ export declare class NavigationIndex {
      */
     private isBodyless;
     /**
-     * Types in the tree that declare a **runnable** `method` and are `fqn` or
-     * below it.
+     * Types in the tree that declare a **runnable** override of `o` and are
+     * `fqn` or below it.
      *
      * "Runnable" is the whole of it: `candidates` answers "which body could
      * run", so an abstract declaration does not belong there even when it is

package/dist/navigation/navigation-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation-index.d.ts","sourceRoot":"","sources":["../../src/navigation/navigation-index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"navigation-index.d.ts","sourceRoot":"","sources":["../../src/navigation/navigation-index.ts"],"names":[],"mappings":"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"}