# Summaries in Dart analyzer

The purpose of this document is to provide a high-level overview of the summaries linking, storage format, and reading
in Dart analyzer.

## Design Considerations

There are a couple of considerations to keep in mind when discussing the design.

**We want the linking to be done using AST.** Default values, constructor initializers, and field initializers should be
stored in their resolved state, with elements and type, because we need them to perform constant evaluation.

**We want separation between AST and resolution.** Files change rarely, usually the user changes just one file, and this
affects resolution of this file and a multiple other files. But only the resolution, not AST. So, we want to keep pieces
that are not affected by the change.

**We want to read only as much as necessary to do resolution.** Libraries often have many classes, but when we resolve a
file, we don’t need all these classes, only those that are actually referenced. So, we want the format to support
loading individual classes, functions, etc.

## High level view

When the analyzer needs to resolve a file, it works in the following way:

1. Find the library cycle that contains this file, and library cycles of its dependencies, down to SDK.

2. Link these library cycles from SDK up to the target cycle.

3. Add linked bundles to `LinkedElementFactory`.

4. When we need a specific element, we call `LinkedElementFactory.elementOfReference`. It will request parent elements,
   and eventually load the containing library, the containing class, method, etc.

## Lazy loading

We try to load only libraries that are necessary. When a `PackageBundleReader` is created, it decodes only the header of
the bundle - with the list of library URIs contained in the bundle, and creates `LibraryReader`s.

When `LinkedElementFactory.createLibraryElementForReading` is invoked, the corresponding `LibraryReader` is asked to
load units, which are `UnitReader`s. Each `UnitReader` keeps track of the location of its AST and resolution portions
in `astReader` and `resolutionReader`. When `UnitReader` is created, it reads the index of top-level declarations, and
fills `Reference` subtree. For each `Reference` we set its `nodeAccessor`, a pointer to the `_UnitMemberReader`, which
can be used to load the corresponding AST node. This is a way to present the index of the unit to `LinkedElementFactory`
.

To support lazy loading the package bundle has the index of libraries, the library has the index of units, the unit has
the index of top-level declarations, the class / extension / mixin has the index of members.

Any time when we need the element for a `Reference`, we call `elementOfReference` of `LinkedElementFactory`, which
asks `Reference.nodeAccessor` for the AST node, and then creates the corresponding `Element` wrapper around it, and
stores into `Reference.element`. For example for `ClassDeclaration` it will create `ClassElement`. No resolution is
required yet.

When `Reference.element` is already set, we just return it, we have already done loading AST node and creating the
element for this `Reference`.

When we link libraries, we don’t use `LinkedElementFactory` to read nodes and create elements, because we already have
full ASTs, and we can create elements for all nodes in advance, and put them into corresponding `Reference` children.

We say that we need the element for a `Reference` because resolution stores elements as such references - a pair of the
name, and the parent reference. So, we may have an empty `Reference` first, without `element` and `nodeAccessor`, then
when `elementOfReference` is invoked, it will fill both for a `Reference`. But its siblings will stay unfilled.

When we ask an `Element` anything that requires resolution, we apply resolution to the whole AST node of the element.
For example, when we ask `ClassElement` for `supertype`, we apply resolution to the `ClassDeclaration` header (but not
to any member of the `ClassDeclaration`) - supertype, mixins, interfaces. We do this by calling `applyResolution`
of `AstLinkedContext`. We get `AstLinkedContext` from the node, which implements `HasAstLinkedContext`.

`AstBinaryWriter` writes two streams of information at once - the AST itself, and resolution. In the future we might
split writing AST and resolution into separate writers.

Resolution information is just a sequence of elements and types, which is stored when we visit the resolved AST
in `AstBinaryWriter`. We use the helper `_ResolutionSink` to encode elements and types into bytes.

Resolution is applied to unresolved AST using `ApplyResolutionVisitor`, which visits AST nodes in the same sequence
as `AstBinaryWriter`, and takes either elements or types from the same (untyped, unmarked in any way) stream of
resolution bytes. `LinkedResolutionReader` corresponds to `_ResolutionSink` - it decodes elements and types from bytes.

Each raw element is represented by an integer, an index in the reference table. This table is collected during writing
in `_BundleWriterReferences`, and stored by `BundleWriterResolution` during `BundleWriter.finish()`. During
loading `BundleReader` creates `_ReferenceReader`, which lazily converts names and parent references into `Reference`
instances in the given `LinkedElementFactory` (from which we just take `rootReference`, not actually any elements). Once
we have `Reference` for the element that we need to decode, we actually ask `LinkedResolutionReader` for the element,
see above.

In addition to raw elements, there are “members” (which is not the best name) - which might be `Element`s which we want
to convert to legacy because they are declared in a null safe library, but we want their legacy types; or actually
members of a class with type parameters and with some `Substitution` applied to them; or both.

Strings are encoded as integers, during writing using `StringIndexer`, and during loading using `_StringTable`. We
use `SummaryDataReader` to load primitive types, and also strings.

## Known limitations

Currently `LibraryScope` and its basis `_LibraryImportScope` and `PrefixScope` - they all work by asking all elements
from the imported libraries. Which means that we load all top-level nodes of these libraries (and all libraries that
they export). Fortunately we don’t apply resolution to these elements until we try to access some property of these
elements, e.g. the return type of a getter. But still, we probably don’t actually use all the imported elements, and we
potentially could avoid loading all these AST nodes. A solution could be to work with `Reference`s instead.

Similarly `InheritanceManager3` builds the whole interface of a class, and loads all members of the class and all
members of all its superinterfaces. But again, we might only call a few methods, and might not need any superinterfaces.
A solution might be to fill class interfaces on demand.