Document internals of compiler
BUG=
R=efortuna@google.com, johnniwinther@google.com
Review-Url: https://codereview.chromium.org/2741853003 .
diff --git a/pkg/compiler/README.md b/pkg/compiler/README.md
new file mode 100644
index 0000000..e4c76b0
--- /dev/null
+++ b/pkg/compiler/README.md
@@ -0,0 +1,821 @@
+# The dart2js compiler
+
+Welcome to the sources of the dart2js compiler!
+
+## Architecture
+
+The compiler is currently undergoing a long refactoring process. As you navigate
+this code you may find it helpful to understand how the compiler used to be,
+where it is going, and where it is today.
+
+### The near future architecture
+
+The compiler will operate in these general phases:
+
+ 1. **load kernel**: Load all the code as kernel
+ * Collect dart sources transtively
+ * Convert to kernel AST
+ (this is will handled by invoking the front-end package)
+
+ Alternatively, the compiler can start compilation directly from a kernel
+ file(s).
+
+ 2. **model**: Create a Dart model of the program
+ * The kernel ASTs could be used as a model, so this might be a no-op or just
+ creating a thin wrapper on top of kernel.
+
+ 3. **tree-shake and create world**: Build world of reachable code
+ * For each reachable piece of code:
+ * Compute impact (i1) from kernel AST
+ * Build a closed world (w1)
+
+ 4. **analyze**: Run a global analysis
+ * Assume closed world semantics (from w1)
+ * Produce a global result (g)
+ * Like today (g) will contain type and nullability information
+ * After we adopt strong-mode types, we want to explore simplifying this
+ to only contain native + nullability information.
+
+ 5. **codegen model**: Create a JS model of the program
+ * Model JavaScript specific concepts (like the split of constructor bodies
+ as separate elements) and provide a mapping to the Dart model
+
+ 6. **codegen and tree-shake**: Generate code, as needed
+ * For each reachable piece of code:
+ * build ssa graph from kernel ASTs and global results (g)
+ * optimize ssa
+ * compute impact (i2) from optimized code
+ * emit JS ASTs for the code
+ * Build a codegen closed world (w2) from new impacts (i2)
+
+ 7. **emit**: Assemble and minify the program
+ * Build program structure from the compiled pieces (w2)
+ * Use frequency namer to minify names.
+ * Emit js and source map files.
+
+### The old architecture
+
+The compiler used to operate as follows:
+
+ 1. **load dart**: Load all source files
+ * Collect dart sources transtively
+ * Scan enough tokens to build import dependencies.
+
+ 2. **model**: Create a Dart model (aka. Element Model) of the program
+ * Do a diet-parse of the program to create the high-level element model
+
+ 3. **resolve and tree-shake**: Resolve and build world of reachable code (the
+ resolution enqueuer)
+ * For each reachable piece of code:
+ * Parse the full body of the function
+ * Resolve it and enqueue other pieces that are reachable
+ * Type check the body of the function
+
+ 5. **analyze**: Run a global analysis
+ * Assume closed world semantics (from everything enqueued by the resolver)
+ * Produce a global result about type and nullability information of method
+ arguments, return values, and receivers of dynamic sends.
+
+ 6. **codegen and tree-shake**: Generate code, as needed (via the codegen
+ enqueuer)
+ * For each reachable piece of code:
+ * build ssa graph from resolved source ASTs global results (g)
+ * optimize ssa
+ * enqueue visible dependencies
+ * emit js asts for the code
+
+ 7. **emit**: Assemble and minify the program
+ * Build program structure from the compiled pieces
+ * Use frequency namer to minify names.
+ * Emit js and source map files.
+
+### The architecture today (which might be changing while you read this!)
+
+When using the `--use-kernel` flag, you can test the latest state of the
+compiler as we are migrating to the new architecture. Currently it works as
+follows:
+
+ 1. **load dart**: (same as old compiler)
+
+ 2. **model**: (same element model as old compiler)
+
+ 3. **resolve, tree-shake and build world**: Build world of reachable code
+ * For each reachable piece of code:
+ * Parse full body of the function
+ * Resolve it from the parsed source ASTs
+ * Type check it (same as old compiler)
+ * Compute impact (i1) from resolved source ASTs (no kernel)
+ * Build a closed world (w1)
+
+ 6. **kernelize**: Create kernel ASTs
+ * For all resolved elements in w1, compute their kernel representation using
+ the `rasta` visitor.
+
+ 5. **analyze**: (almost same as old compiler)
+
+ 6. **codegen and tree-shake**: Generate code, as needed
+ * For each reachable piece of code:
+ * build ssa graph from kernel ASTs (uses global results g)
+ * optimize ssa
+ * compute impact (i2) from optimized code
+ * emit js asts for the code
+ * Build a codegen closed world (w2) from new impacts (i2)
+
+ 7. **emit**: (same as old compiler)
+
+Some additional details worth highlighting:
+
+ * tree-shaking is close to working as we want: the notion of a world and world
+ impacts are computed explicitly:
+
+ * In the old compiler, the resolver and code generator directly
+ enqueued items to be processed, there was no knowledge of what had
+ to be done other than in the algorithm itself.
+
+ * Now the information is computed explicitly in two ways:
+
+ * The dependencies of a single element are computed as an "impact"
+ object, these are derived from the structure of the
+ code (either the resolved code or the generated code).
+
+ * The closed world is now an explicit concept that can be replaced in the
+ compiler.
+
+ * This allows us to delete the resolver in the future and replace it
+ with a kernel loader, an impact builder from kernel, and a kernel world.
+
+ * There is an implementation of a kernel impact builder, but it is not yet
+ in use in the compiler pipeline (gated on replacing the Dart model)
+
+ * We still depend on the Dart model computed by resolution, but progress has
+ been made introducing an abstraction common to the new and old models. The
+ old model is the "Element model", the generic abstraction is called the
+ "Entity model". Some portions of the compiler now refer to the entity model.
+
+ * The ssa graph is built from the kernel ASTs, but it still depends on the old
+ element model computed from resolution (accessed via a kernel2Ast adapter).
+ The graph builder implementation covers a large chunk of the language
+ features, but is not complete (89% of langage & corelib tests are passing).
+
+ * Global analysis is still working on top of the dart2js ASTs.
+
+## Code organization and history
+
+The compiler package was initially intended to be compiler for multiple targets:
+Javascript, Dart (dart2dart), and dartino bytecodes. It has now evolved to be a
+Javascript only compiler, but some of the abstractions to support multiple
+targets still remain.
+
+### Possibly confusing terminology
+
+Some of the terminology in the compiler is confusing without knowing its
+history. We are cleaning this up as we are rearchitecting the system, but here
+are some of the legacy terminology we have:
+
+ * **target**: the output the compiler is producing. Nowdays it just
+ JavaScript, but in the past there was also Dart and dartino bytecodes.
+
+ * **backend**: pieces of the compiler that were target-specific.
+ Note: in the past we've used the term *backend* also for code that is used
+ in the frontend of the compiler that happens to be target-specific, as well
+ as and code that is used in the emitter or what traditionally is known
+ as the backend of the compiler.
+
+ * **frontend**: the parser, resolver, and other early stages of the compiler.
+ The front-end however makes target-specific choices. For example, to compile
+ a program with async-await, the dart2js backend needs to include some helper
+ functions that are used by the expanded async-await code, these helpers need
+ to be parsed by the frontend and added to the compilation pipeline.
+
+ * **world**: the compiler exploits closed-world assumptions to do
+ optimizations. The *world* encapsulates some of our knowledge of the
+ program, like what's reachable from `main`, which classes are instantiated,
+ etc.
+
+ * **universe**: rather than loading entire programs and removing unreachable
+ code, the compiler uses a tree-growing approach: it enqueues work based on
+ what it sees. While this is happening the *world* is considered to be
+ growing, in the past the term *universe* was used to describe this growing
+ world. While the term is not completely deleted from the codebase, a lot of
+ progress has been made to rename *universe* into *world builders*.
+
+ * **model**: there are many models in the compiler:
+
+ * **element model**: this is an abstraction describing the elements seen in
+ Dart programs, like "libraries", "classes", "methods", etc.
+
+ * **entity model**: also describes elements seen in Dart programs, but it is
+ meant to be minimalistic and a super-hierarcy above the *element models*.
+ This is a newer addition, is an added abstraction to make it possible to
+ refactor our code from our old frontend to the kernel frontend.
+
+ * **Dart vs JS models**: the compiler in the past had a single model to
+ describe elements in the source and elements that were being compiled. In
+ the future we plan to have two. Both input model and output models will be
+ implementations of the *entity model*. The JS model is intended to have
+ concepts specific about generating code in JS (like constructor-bodies as
+ a separate entity than the constructor, closure classes, etc).
+
+ * **emitter model**: this is a model just used for dumping out the structure
+ of the program in a .js text file. It doesn't have enough semantic meaning
+ to be a JS model for compilation at this moment.
+
+ * **enqueuer**: a work-queue used to achieve tree-shaking (or more precisely
+ tree-growing): elements are added to the enqueuer as we recognize that they
+ are needed in a given application. Note that we even track how elements are
+ used, since some ways of using an element require more code than others.
+
+### Code layout
+
+Here are some details of our current code layout and what's on each file. This
+list also includes some action items (labeled AI below), which are mainly
+cleanup tasks that we have been discussing for a while:
+
+**bin folder**: some experimental command-line entrypoints, these need to be
+revisited
+
+* `bin/dart2js.dart`: is a dart2js entry point, not used today other than
+ locally for development, most of our tools launch dart2js from
+ `lib/src/dart2js.dart` instead.
+
+ AI: change how we build the SDK to launch dart2js from here, most logic might
+ remain inside `lib/src/dart2js.dart` for testing purposes.
+
+* `bin/resolver.dart`: an experiemntal binary we used to run the resolver and
+ serializer. As we are moving to work on top of kernel this is deprecated and
+ should be deleted.
+
+ AI: delete this file.
+
+**lib folder**: API to use dart2js as a library. This is used by our
+command-line tool to launch dart2js, but also by pub to invoke dart2js as a
+library during `pub-build` and `pub-serve`.
+
+* `lib/compiler_new.dart`: the current API. This API is used by our command-line
+ tool to spawn the dart2js compiler. This API (and everything that is
+ transitively created from it) has no dependencies on `dart:io` so that the
+ compiler can be used in contexts where `dart:io` is not available (e.g.
+ running in a browser worker) or where `dart:io` is not used explicitly (e.g.
+ running as a pub transformer).
+
+ AI: rename to `compiler.dart`.
+
+* `lib/compiler.dart`: a legacy API that now is implemented by adapting calls to
+ the new API in `compiler_new.dart`.
+
+ AI: migrate users to the new API (pub is one of those users, possibly dart-pad
+ is another), and delete the legacy API.
+
+**lib/src folder**: most of the compiler lives here, as very little of its
+funtionality is publicly exposed.
+
+
+* `lib/src/dart2js.dart`: the command-line script that runs dart2js. When
+ building the SDK, the dart2js snapshot is built using the main method on this
+ script. This file creates the parameters needed to invoke the API defined in
+ `lib/compiler_new.dart`. All dependencies on `dart:io` come from here. This is
+ also where we process options (although some of the logic is done in
+ `options.dart`).
+
+* `lib/src/compiler.dart`: defines the core `Compiler` object, which contains
+ all the logic about what the compiler pipeline does and how data is organized
+ and communicated between different phases. For a long time, `Compiler` was
+ also used throughout the system as a global dependency-injection object.
+ We've been slowly disentangling those dependencies, but there are still many
+ references to `compiler` still in use.
+
+* `lib/src/apiimpl.dart`: defines `CompilerImpl` a subclass of `Compiler` that
+ adds support for loading scripts, resolving package URIs and patch files. The
+ separation here is a bit historical and we should be able to remove it. It was
+ added to make it easier to create a `MockCompiler` implementation for unit
+ testing. The `MockCompiler` has been replaced in most unit tests by a regular
+ `CompilerImpl` that uses a mock of the file-system (see
+ `tests/compiler/dart2js/memory_compiler.dart`).
+
+ AI: Once all tests are migrated to this memory compiler, we should merge
+ `Compiler` and `CompilerImpl` and remove this file.
+
+* `lib/src/old_to_new_api.dart`: helper library used to adapt the public API in
+ `lib/compiler.dart` to `lib/compiler_new.dart`.
+
+* `lib/src/closure.dart`: closures are compiled as classes, this file has the
+ logic to do this kind of conversion in the Dart element model. This includes
+ computing what needs to be boxed and creating fake element models to represent
+ closures as classes. We use the fake model approach because the compiler
+ currently uses the same element model for Dart and JS. Our goal with the
+ compiler rearchitecture described earlier is to have two models. The
+ Dart model will be able to encode closures directly, and we'll introduce their
+ corresponding classes when we create the corresponding JS model, removing the
+ need of the fake elements.
+
+* `lib/src/colors.dart`: ANSII support for reporting error messages with colors.
+
+ AI: this file should move under a utilities folder.
+
+
+* Handling of options: as mentioned earlier `lib/src/dart2js.dart` has some
+ handling of command-line options, the rest is divided into these files:
+
+ * `lib/src/commandline_options.dart`: defines the flags that dart2js accepts.
+
+ * `lib/src/options.dart`: defines first-class objects to represent options of
+ dart2js. This includes a parse function that can translate flags into their
+ corresponding objects. This was added recently to simplify how options were
+ propagated throughout the compiler.
+
+ AI: simplify further how we specify options. Ideally all changes can be done
+ in a single file (`options.dart`?), and unit-tests can specify options via an
+ options object rather than command-line flags.
+
+* `lib/src/common.dart`: convenience file that reexports code used in many
+ places in the compiler.
+
+ AI: consider deleting this file.
+
+
+* Constants: the compiler has a constant system that delays evaluation of
+ constants and provides different semantics depending on the embedder, this
+ abstraction was especially necessary when dart2js was used as a front-end for
+ non-JS systems like dart2dart and dartino.
+
+ * `lib/src/constants/expressions.dart`: this is how constants are represented
+ after they are parsed but before they are evaluated. It is a target
+ agnostic representation, all expressions are kept as they appear in the
+ source, and it doesn't replace _environemnt_ values that are provided on the
+ command line. In particular, the constant `1 == 1.0` is represented as an
+ expression that includes the `==` binary expression, and `const
+ String.fromEnvironment("FOO")` is not expanded.
+
+ * `lib/src/constants/value.dart`: this is the represented value of a constant
+ after it has been evaluated. The resulting value is specific to the target
+ of the compiler and will no longer have environment placeholders. For
+ example, when the target is Dart (dart2dart) `1 == 1.0` is evaluated to
+ `false`, and when the target is JavaScript it is evaluated to `true`. This
+ specific example is a result of the way dart2js compiles numbers as
+ JavaScript Numbers.
+
+ * `lib/src/constants/evaluation.dart`: defines the algorithm to turn an
+ expression into a value.
+
+ * `lib/src/constants/constant_system.dart`: an abstraction that defines how
+ expressions may be folded. Different implementations of the constant system
+ are used to target Dart or JavaScript.
+
+ * `lib/src/compile_time_constants.dart`: defines how constant expresions are
+ created from a parsed AST.
+
+ * `lib/src/constant_system_dart.dart`: defines an implementation of a constant
+ system with the Dart semantics (where `1 == 1.0` is true).
+
+ * `lib/src/js_backend/constant_system_javascript.dart`: defines an
+ implementation of a constant system with the JavaScript semantics (where
+ `1 == 1.0` is false).
+
+ * `lib/src/constants/constructors.dart` and
+ `lib/src/constants/constant_constructors.dart`: used to define expressions
+ containing constant constructors. They depend on the resolver to figure out
+ what is the meaning of an initializer or a field on a constructed constant
+ created this way.
+
+ AI: consider deleting `constant_system_dart.dart` now that it is no longer
+ used, or move under testing, if it might be used for unittests of the constant
+ expressions.
+
+* Common elements: the compiler often refers to certain elements during
+ compilation either because they are first-class in the language or because
+ they are implicitly used to implement some features. These include:
+
+ * `lib/src/common_elements.dart`: provides an interface to lookup basic
+ elements like the class of `Object`, `int`, `List`, and their corresponding
+ interface types, constructors for symbols, annotations such as
+ `@MirrorsUsed`, the `identical` function, etc. These are normally restricted
+ to elements that are understood directly in Dart.
+
+ * `lib/src/js_backend/backend_helpers.dart`: provides a way to lookup internal
+ elements of the Javascript backend, like our internal
+ representation of JSInt31, JSArray, and other implementation-specific
+ elements.
+
+* `lib/src/dart2js_resolver.dart`: a script to run the compiler up to resolution
+ and to generate a serialized json representation of the element model.
+
+ AI: delete.
+
+* `lib/src/deferred_load.dart`: general analysis for deferred loading. This is
+ where we compute how to split the code in different JS chunks or fragments.
+ This is run after resolution, but at a time when no code is generated yet, so
+ the decisions made here are used later on by the emitter to dump code into
+ different files.
+
+* `lib/src/dump_info.dart`: a special phase used to create a .info.json file.
+ This file contains lots of information computed by dart2js including decisions
+ about deferred loading, results of the global type-inference, and the actual
+ code generated for each function. The output is used by tools provided in the
+ `dart2js_info` package to analyze a program and better understand why
+ something wasn't optimized as you'd expect.
+
+* Tree-shaking: The compiler does two phases of reducing the program size by
+ throwing away unreachable code. The first phase is done while resolving the
+ program (reachablity is basically based on dependencies that appear in the
+ code), the second phase is done as functions are optimized (which in turn can
+ delete branches of the code and make more code unreachable). Externally
+ we refer to it as tree-shaking, but it behaves more like a tree-growing
+ algorithm: elements are added as they are discovered or as they are used.
+ On some large apps we've seen 50% of code tree-shaken: 20% from the first
+ phase, and an additional 30% from the second phase.
+
+ * `lib/src/enqueue.dart`: this is the basic algorithm that adds things as they
+ are discovered during resolution.
+
+ * `lib/src/js_backend/enqueuer.dart`: this is the enqueuer used during code
+ generation.
+
+* `lib/src/environment.dart`: simple interface for collecting environment values
+ (these are values passed via -D flags on the command line).
+
+* `lib/src/filenames.dart`: basic support for converting between native and Uri
+ paths.
+
+ AI: move to utils
+
+* `lib/src/id_generator.dart`: simple id generator
+
+ AI: move to utils
+
+* `lib/src/library_loader.dart`: the loader of the dart2js frontend. Asks the
+ compiler to read and scan files, produce enough metadata to understand
+ import, export, and part directives and keep crawling. It also triggers the
+ patch parser to load patch files.
+
+* `lib/src/mirrors_used.dart`: task that analyzes `@MirrorsUsed` annotations,
+ which let the compiler continue to do tree-shaking even when code is used via
+ `dart:mirrors`.
+
+* Input/output: the compiler is designed to avoid all dependencies on dart:io.
+ Most data is consumed and emitted via provider APIs.
+
+ * `lib/src/compiler_new.dart`: defines the interface of these providers (see
+ `CompilerInput` and `CompilerOutput`).
+
+ * `lib/src/null_compiler_output.dart`: an `CompilerOutput` that discards all
+ data written to it (name derives from /dev/null).
+
+ * `lib/src/source_file_provider.dart`: _TODO: add details_.
+
+* Parsing: most of the parsing logic is now in the `front_end` package,
+ currently under `pkg/front_end/lib/src/fasta/scanner` and
+ `pkg/front_end/lib/src/fasta/parser`. The `front_end` parser is AST agnostic
+ and uses listeners to create on the side what they want as the result of
+ parsing. The logic to create dart2js' ASTs is defined in listeners within the
+ compiler package:
+
+ * `lib/src/parser/element_listener.dart`: listener used to create the first
+ skeleton of the element model (used by the diet parser)
+
+ * `lib/src/parser/partial_elements.dart`: representation of elements in the
+ element model whose body is not parsed yet (e.g. a diet-parsed member).
+
+ * `lib/src/parser/node_listener.dart`: listener used to create the body of
+ methods.
+
+ * `lib/src/parser/member_listener.dart`: listener used to attach method bodies
+ to class members.
+
+ * `lib/src/parser/parser_task.dart`: Task to execute the full parser.
+
+ * `lib/src/parser/diet_parser_task.dart`: Task to execute diet parsing.
+
+ * `lib/src/patch_parser.dart`: additional support for parsing patch files. We
+ expect this will also move under `front_end` in the future.
+
+
+* URI resolution: the compiler needs special logic to resolve `dart:*` URIs and
+ `package:*` URIs. These are specified in three parts:
+
+ * sdk library files are specified in a .platform file. This file has a special
+ .ini format which is parsed with `lib/src/platform_configuration.dart`.
+
+ * sdk patch files are hardcoded in the codebase in
+ `lib/src/js_backend/backend.dart` (see `_patchLocations`).
+
+ * package resolution is specified with a `.packages` file, which is parsed
+ using the `package_config` package.
+
+ * `lib/src/resolved_uri_translator.dart`: has the logic to translate all these
+ URIs when they are encountered by the library loader.
+
+ AI: consider changing the .platform file format to yaml.
+
+
+* `lib/src/typechecker.dart`: the type checker (spec mode semantics, no support
+ for strong mode here).
+
+* World: _TODO: add details_
+
+ * `lib/src/world.dart`
+ * `lib/src/universe/call_structure.dart`
+ * `lib/src/universe/use.dart`
+ * `lib/src/universe/feature.dart`
+ * `lib/src/universe/world_impact.dart`
+ * `lib/src/universe/selector.dart`
+ * `lib/src/universe/side_effects.dart`
+ * `lib/src/universe/class_set.dart`
+ * `lib/src/universe/world_builder.dart`
+ * `lib/src/universe/function_set.dart`
+
+
+* Testing, debugging, and what not: _TODO: add details_
+ * `lib/src/tracer.dart`
+ * `lib/src/use_unused_api.dart`
+
+
+* SSA (`lib/src/ssa`): internal IR used to optimize functions before emitting
+ JavaScript. _TODO: add details_.
+ * `ssa.dart`
+ * `kernel_string_builder.dart`
+ * `codegen.dart`
+ * `variable_allocator.dart`
+ * `type_builder.dart`
+ * `value_set.dart`
+ * `types.dart`
+ * `jump_handler.dart`
+ * `codegen_helpers.dart`
+ * `switch_continue_analysis.dart`
+ * `types_propagation.dart`
+ * `nodes.dart`
+ * `kernel_ast_adapter.dart`
+ * `graph_builder.dart`
+ * `validate.dart`
+ * `builder.dart.rej`
+ * `interceptor_simplifier.dart`
+ * `builder_kernel.dart`
+ * `locals_handler.dart`
+ * `optimize.dart`
+ * `kernel_impact.dart`
+ * `invoke_dynamic_specializers.dart`
+ * `builder.dart`
+ * `ssa_branch_builder.dart`
+ * `value_range_analyzer.dart`
+ * `ssa_tracer.dart`
+ * `loop_handler.dart`
+
+* `tool`: some helper scripts, some of these could be deleted
+
+ * `tool/perf.dart`: used by our benchmark runners to measure performance of
+ some frontend pieces of dart2js. We shuld be able to delete it in the near
+ future once the front end code is moved into `fasta`.
+
+ * `tool/perf_test.dart`: small test to ensure we don't break `perf.dart`.
+
+ * `tool/track_memory.dart`: a helper script to see memory usage of dart2js
+ while it's running. Used in the past to profile the global analysis phases
+ when run on very large apps.
+
+ * `tool/dart2js_stress.dart` and `tool/dart2js_profile_many.dart`: other
+ helper wrappers to make it easier to profile dart2js with Observatory.
+
+* Source map tracking (`lib/src/io`): helpers used to track source information
+ and to build source map files. _TODO: add details_.
+ * `lib/src/io/code_output.dart`
+ * `lib/src/io/source_map_builder.dart`
+ * `lib/src/io/start_end_information.dart`
+ * `lib/src/io/position_information.dart`
+ * `lib/src/io/source_information.dart`
+ * `lib/src/io/source_file.dart`
+ * `lib/src/io/line_column_provider.dart`
+
+* Kernel conversion (`lib/src/kernel`): temporary code to create kernel within
+ dart2js (previously known as `rasta`). Most of this code will be gone when we
+ are in the final architecture. _TODO: add details_.
+ * `lib/src/kernel/task.dart`
+ * `lib/src/kernel/kernel_visitor.dart`
+ * `lib/src/kernel/kernel_debug.dart`
+ * `lib/src/kernel/unresolved.dart`
+ * `lib/src/kernel/kernel.dart`
+ * `lib/src/kernel/unavailable.dart`
+ * `lib/src/kernel/accessors.dart`
+ * `lib/src/kernel/constant_visitor.dart`
+ * `lib/src/kernel/error.dart`
+
+* Global whole-program analysis (a.k.a. type inference): We try to avoid the
+ term "type inference" to avoid confusion with strong-mode type inference.
+ However the code still uses the term inference for this global analysis. The
+ code is contained under `lib/src/inferrer`. _TODO: add details_.
+ * `lib/src/inferrer/type_graph_dump.dart`
+ * `lib/src/inferrer/node_tracer.dart`
+ * `lib/src/inferrer/list_tracer.dart`
+ * `lib/src/inferrer/closure_tracer.dart`
+ * `lib/src/inferrer/inferrer_engine.dart`
+ * `lib/src/inferrer/type_graph_inferrer.dart`
+ * `lib/src/inferrer/type_graph_nodes.dart`
+ * `lib/src/inferrer/type_system.dart`
+ * `lib/src/inferrer/debug.dart`
+ * `lib/src/inferrer/locals_handler.dart`
+ * `lib/src/inferrer/map_tracer.dart`
+ * `lib/src/inferrer/builder.dart`
+
+* Serialization (`lib/src/serialization/*`: the compiler had support to emit a
+ serialized form of the element model. This is likely going to be deleted in
+ the near future (it was created before we had the intent to use kernel as a
+ serialization format).
+
+---------
+
+_TODO: complete the documentation for the following files_.
+
+`lib/src/ordered_typeset.dart`
+`lib/src/script.dart`
+`lib/src/string_validator.dart`
+
+`lib/src/native`
+`lib/src/native/ssa.dart`
+`lib/src/native/scanner.dart`
+`lib/src/native/js.dart`
+`lib/src/native/enqueue.dart`
+`lib/src/native/behavior.dart`
+`lib/src/native/native.dart`
+
+`lib/src/js_emitter`
+`lib/src/js_emitter/native_emitter.dart`
+`lib/src/js_emitter/main_call_stub_generator.dart`
+`lib/src/js_emitter/model.dart`
+`lib/src/js_emitter/headers.dart`
+`lib/src/js_emitter/native_generator.dart`
+`lib/src/js_emitter/parameter_stub_generator.dart`
+`lib/src/js_emitter/constant_ordering.dart`
+`lib/src/js_emitter/program_builder`
+`lib/src/js_emitter/program_builder/collector.dart`
+`lib/src/js_emitter/program_builder/program_builder.dart`
+`lib/src/js_emitter/program_builder/field_visitor.dart`
+`lib/src/js_emitter/program_builder/registry.dart`
+`lib/src/js_emitter/metadata_collector.dart`
+`lib/src/js_emitter/code_emitter_task.dart.rej`
+`lib/src/js_emitter/code_emitter_task.dart.orig`
+`lib/src/js_emitter/code_emitter_task.dart`
+`lib/src/js_emitter/interceptor_stub_generator.dart`
+`lib/src/js_emitter/full_emitter`
+`lib/src/js_emitter/full_emitter/class_builder.dart`
+`lib/src/js_emitter/full_emitter/container_builder.dart`
+`lib/src/js_emitter/full_emitter/deferred_output_unit_hash.dart`
+`lib/src/js_emitter/full_emitter/class_emitter.dart`
+`lib/src/js_emitter/full_emitter/interceptor_emitter.dart`
+`lib/src/js_emitter/full_emitter/code_emitter_helper.dart`
+`lib/src/js_emitter/full_emitter/emitter.dart`
+`lib/src/js_emitter/full_emitter/setup_program_builder.dart`
+`lib/src/js_emitter/full_emitter/declarations.dart`
+`lib/src/js_emitter/full_emitter/nsm_emitter.dart`
+`lib/src/js_emitter/type_test_registry.dart`
+`lib/src/js_emitter/js_emitter.dart.rej`
+`lib/src/js_emitter/class_stub_generator.dart`
+`lib/src/js_emitter/lazy_emitter`
+`lib/src/js_emitter/lazy_emitter/model_emitter.dart`
+`lib/src/js_emitter/lazy_emitter/emitter.dart`
+`lib/src/js_emitter/startup_emitter`
+`lib/src/js_emitter/startup_emitter/deferred_fragment_hash.dart`
+`lib/src/js_emitter/startup_emitter/model_emitter.dart`
+`lib/src/js_emitter/startup_emitter/emitter.dart`
+`lib/src/js_emitter/startup_emitter/fragment_emitter.dart`
+`lib/src/js_emitter/js_emitter.dart`
+`lib/src/js_emitter/helpers.dart`
+`lib/src/js_emitter/runtime_type_generator.dart`
+`lib/src/js_emitter/js_emitter.dart.orig`
+
+`lib/src/elements`
+`lib/src/elements/modelx.dart`
+`lib/src/elements/types.dart`
+`lib/src/elements/resolution_types.dart`
+`lib/src/elements/entities.dart`
+`lib/src/elements/common.dart`
+`lib/src/elements/names.dart`
+`lib/src/elements/visitor.dart`
+`lib/src/elements/elements.dart`
+
+`lib/src/diagnostics`
+`lib/src/diagnostics/invariant.dart`
+`lib/src/diagnostics/generated`
+`lib/src/diagnostics/generated/shared_messages.dart`
+`lib/src/diagnostics/messages.dart`
+`lib/src/diagnostics/source_span.dart`
+`lib/src/diagnostics/code_location.dart`
+`lib/src/diagnostics/diagnostic_listener.dart`
+`lib/src/diagnostics/spannable.dart`
+
+`lib/src/common`
+`lib/src/common/codegen.dart`
+`lib/src/common/resolution.dart`
+`lib/src/common/tasks.dart`
+`lib/src/common/work.dart`
+`lib/src/common/backend_api.dart`
+`lib/src/common/names.dart`
+
+`lib/src/tokens/token_map.dart`: unused
+
+`lib/src/resolution`
+`lib/src/resolution/typedefs.dart`
+`lib/src/resolution/registry.dart.orig`
+`lib/src/resolution/scope.dart`
+`lib/src/resolution/members.dart`
+`lib/src/resolution/label_scope.dart`
+`lib/src/resolution/registry.dart.rej`
+`lib/src/resolution/resolution.dart`
+`lib/src/resolution/access_semantics.dart`
+`lib/src/resolution/operators.dart`
+`lib/src/resolution/member_impl.dart`
+`lib/src/resolution/resolution_common.dart`
+`lib/src/resolution/semantic_visitor.dart`
+`lib/src/resolution/resolution_result.dart`
+`lib/src/resolution/send_resolver.dart`
+`lib/src/resolution/send_structure.dart`
+`lib/src/resolution/variables.dart`
+`lib/src/resolution/enum_creator.dart`
+`lib/src/resolution/members.dart.orig`
+`lib/src/resolution/type_resolver.dart`
+`lib/src/resolution/class_members.dart`
+`lib/src/resolution/constructors.dart`
+`lib/src/resolution/secret_tree_element.dart`
+`lib/src/resolution/registry.dart`
+`lib/src/resolution/tree_elements.dart`
+`lib/src/resolution/semantic_visitor_mixins.dart`
+`lib/src/resolution/class_hierarchy.dart`
+`lib/src/resolution/signatures.dart`
+
+`lib/src/scanner`
+`lib/src/scanner/scanner_task.dart`
+
+`lib/src/helpers`
+`lib/src/helpers/trace.dart`
+`lib/src/helpers/debug_collection.dart`
+`lib/src/helpers/expensive_map.dart`
+`lib/src/helpers/helpers.dart`
+`lib/src/helpers/track_map.dart`
+`lib/src/helpers/expensive_set.dart`
+`lib/src/helpers/stats.dart`
+
+`lib/src/js`
+`lib/src/js/js.dart`
+`lib/src/js/placeholder_safety.dart`
+`lib/src/js/js_debug.dart`
+`lib/src/js/js_source_mapping.dart`
+`lib/src/js/rewrite_async.dart`
+
+`lib/src/util`
+`lib/src/util/uri_extras.dart`
+`lib/src/util/indentation.dart`
+`lib/src/util/enumset.dart`
+`lib/src/util/link.dart`
+`lib/src/util/util.dart`
+`lib/src/util/maplet.dart`
+`lib/src/util/setlet.dart`
+`lib/src/util/characters.dart`
+`lib/src/util/emptyset.dart`
+`lib/src/util/link_implementation.dart`
+`lib/src/util/util_implementation.dart`
+`lib/src/util/command_line.dart`
+
+`lib/src/js_backend`
+`lib/src/js_backend/frequency_namer.dart`
+`lib/src/js_backend/patch_resolver.dart`
+`lib/src/js_backend/minify_namer.dart`
+`lib/src/js_backend/mirrors_analysis.dart`
+`lib/src/js_backend/js_backend.dart`
+`lib/src/js_backend/field_naming_mixin.dart`
+`lib/src/js_backend/native_data.dart`
+`lib/src/js_backend/namer.dart`
+`lib/src/js_backend/custom_elements_analysis.dart`
+`lib/src/js_backend/type_variable_handler.dart`
+`lib/src/js_backend/js_interop_analysis.dart`
+`lib/src/js_backend/backend_impact.dart`
+`lib/src/js_backend/constant_emitter.dart`
+`lib/src/js_backend/lookup_map_analysis.dart`
+`lib/src/js_backend/namer_names.dart`
+`lib/src/js_backend/runtime_types.dart`
+`lib/src/js_backend/no_such_method_registry.dart`
+`lib/src/js_backend/constant_system_javascript.dart`
+`lib/src/js_backend/backend.dart`
+`lib/src/js_backend/backend_serialization.dart`
+`lib/src/js_backend/checked_mode_helpers.dart`
+`lib/src/js_backend/constant_handler_javascript.dart`
+
+`lib/src/tree`
+`lib/src/tree/prettyprint.dart`
+`lib/src/tree/tree.dart`
+`lib/src/tree/nodes.dart`
+`lib/src/tree/dartstring.dart`
+`lib/src/tree/unparser.dart`
+
+`lib/src/types`
+`lib/src/types/abstract_value_domain.dart`
+`lib/src/types/types.dart`
+`lib/src/types/type_mask.dart`
+`lib/src/types/dictionary_type_mask.dart`
+`lib/src/types/map_type_mask.dart`
+`lib/src/types/forwarding_type_mask.dart`
+`lib/src/types/container_type_mask.dart`
+`lib/src/types/constants.dart`
+`lib/src/types/flat_type_mask.dart`
+`lib/src/types/masks.dart`
+`lib/src/types/value_type_mask.dart`
+`lib/src/types/union_type_mask.dart`
+
+`lib/src/hash`
+`lib/src/hash/sha1.dart`
