Initial package indexing implementation.

pkg/analyzer/lib/src/summary/index_unit.dart

+// Copyright (c) 2016, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:analyzer/dart/ast/ast.dart';
+import 'package:analyzer/dart/ast/token.dart';
+import 'package:analyzer/dart/ast/visitor.dart';
+import 'package:analyzer/dart/element/element.dart';
+import 'package:analyzer/dart/element/type.dart';
+import 'package:analyzer/src/generated/utilities_dart.dart';
+import 'package:analyzer/src/summary/format.dart';
+import 'package:analyzer/src/summary/idl.dart';
+
+/**
+ * Object that gathers information about the whole package index and then uses
+ * it to assemble a new [PackageIndexBuilder].

[Paul Berry, 2016/02/25 23:05:13]

It would be helpful to have a comment here explaining how this class is intended
to be used.  E.g. "Call [index] on each compilation unit to be indexed, then
call [assemble] to retrieve the complete index for the package."

[scheglov, 2016/02/26 04:54:03]

Done.

+ */
+class PackageIndexAssembler {
+  final Map<Element, _ElementInfo> _elementMap = <Element, _ElementInfo>{};
+
+  final Map<CompilationUnitElement, int> _elementUnitMap =

[Paul Berry, 2016/02/25 23:05:12]

Please add doc comments for all these fields.  I've spent a lot of time cross
referencing the code and re-reading the IDL to figure out what they are for, and
I'm still not certain whether my conclusions are correct.

Documentation would be especially helpful for a field like this one, where it's
hard to infer what's going on from the type alone, because I don't know what the
int refers to.  (At first I guessed it was the index of the compilation unit in
[PackageIndex.units], but that turned out to be wrong).

E.g. "Map from a compilation unit to the location in
[PackageIndex.elementUnitUris] and [PackageIndex.elementLibraryUris] where we
will store information about the URIs of the compilation unit."

[scheglov, 2016/02/26 04:54:02]

Done.

+      <CompilationUnitElement, int>{};
+  final List<int> _elementLibraryUris = <int>[];
+  final List<int> _elementUnitUris = <int>[];
+
+  final Map<String, int> _uriMap = <String, int>{};
+  final List<String> _uris = <String>[];
+
+  final List<_UnitIndexAssembler> _units = <_UnitIndexAssembler>[];
+
+  PackageIndexAssembler();
+
+  /**
+   * Assemble a new [PackageIndexBuilder] using the gathered information.

[Paul Berry, 2016/02/25 23:05:12]

s/using the gathered information/using the information gathered by [index]/

[scheglov, 2016/02/26 04:54:02]

Done.

+   */
+  PackageIndexBuilder assemble() {
+    List<_ElementInfo> elements = _elementMap.values.toList();

[Paul Berry, 2016/02/25 23:05:12]

Suggestion: rename this to "elementInfos" to avoid confusion (I keep thinking
it's a list of elements)

[scheglov, 2016/02/26 04:54:02]

Done.

+    elements.sort((a, b) {
+      return a.offset - b.offset;
+    });
+    for (int i = 0; i < elements.length; i++) {
+      elements[i].id = i;
+    }
+    return new PackageIndexBuilder(
+        elementLibraryUris: _elementLibraryUris,
+        elementUnitUris: _elementUnitUris,
+        elementUnits: elements.map((e) => e.unitId).toList(),
+        elementOffsets: elements.map((e) => e.offset).toList(),
+        uris: _uris,
+        units: _units.map((unit) => unit.assemble()).toList());
+  }
+
+  /**
+   * Index the given fully resolved [unit].
+   */
+  void index(CompilationUnit unit) {
+    CompilationUnitElement unitElement = unit.element;
+    _UnitIndexAssembler assembler = new _UnitIndexAssembler(this, unitElement);
+    _units.add(assembler);
+    unit.accept(new _IndexContributor(assembler));
+  }
+
+  _ElementInfo _getElementInfo(Element element) {
+    return _elementMap.putIfAbsent(element, () {
+      CompilationUnitElement unitElement = getUnitElement(element);
+      int unitId = _getUnitElementId(unitElement);
+      return new _ElementInfo(element, unitId);
+    });
+  }
+
+  int _getUnitElementId(CompilationUnitElement element) {

[Paul Berry, 2016/02/25 23:05:12]

Documentation on these private methods would be helpful too.  E.g. "add
information about [element] to [_elementUnitUris] and [_elementLibraryUris] if
necessary, and return the location in those arrays representing [element]."

Suggestion: rename [element] to [compilationUnit] to make the above text easier
to understand.

[scheglov, 2016/02/26 04:54:03]

Done.

+    return _elementUnitMap.putIfAbsent(element, () {
+      assert(_elementLibraryUris.length == _elementUnitUris.length);
+      int id = _elementUnitUris.length;
+      _elementLibraryUris.add(_getUriId(element.library.source.uri));
+      _elementUnitUris.add(_getUriId(element.source.uri));
+      return id;
+    });
+  }
+
+  int _getUriId(Uri uri) {
+    String str = uri.toString();
+    return _uriMap.putIfAbsent(str, () {
+      int id = _uris.length;
+      _uris.add(str);
+      return id;
+    });
+  }
+
+  /**
+   * Return the [CompilationUnitElement] that should be used for [element].
+   */
+  static CompilationUnitElement getUnitElement(Element element) {

[Paul Berry, 2016/02/25 23:05:13]

It looks like this is only used by other code in this file.  Can we rename it to
"_getUnitElement"?  That would help me understand that it's not intended to be
part of the public API to this file.

[scheglov, 2016/02/26 04:54:03]

It is used in tests.
And it also will be used in index clients.
Although the location is not ideal, I don't know whether making it a top-level
function is much better.

+    CompilationUnitElement unitElement;
+    for (Element e = element; e != null; e = e.enclosingElement) {
+      if (e is CompilationUnitElement) {
+        unitElement = e;
+        break;
+      }
+      if (e is LibraryElement) {
+        unitElement = e.definingCompilationUnit;
+        break;
+      }
+    }
+    assert(unitElement != null);
+    return unitElement;
+  }
+}
+
+/**
+ * Information about an element referenced in index.
+ */
+class _ElementInfo {
+  final Element element;

[Paul Berry, 2016/02/25 23:05:13]

It looks like this is only used by the [offset] getter below.  How about getting
rid of it and changing [offset] into a final field?

[scheglov, 2016/02/26 04:54:03]

Done.

+
+  /**
+   * The identifier of the [CompilationUnitElement] containing [element].
+   */
+  final int unitId;
+
+  /**
+   * The unique id of the [element] in the [PackageIndex].  It is set after
+   * after indexing of the whole package is done and we are assembling the
+   * full package index.
+   */
+  int id;
+
+  _ElementInfo(this.element, this.unitId);
+
+  int get offset => element.nameOffset;
+}
+
+/**
+ * Visits a resolved AST and adds relationships into [InternalIndexStore].
+ */
+class _IndexContributor extends GeneralizingAstVisitor {
+  final _UnitIndexAssembler assembler;
+
+  _IndexContributor(this.assembler);
+
+  /**
+   * Record that [element] has a relation of the given [kind] at the location
+   * of the given [node].
+   */
+  void recordRelation(Element element, IndexRelationKind kind, AstNode node) {
+    if (element != null && node != null) {
+      recordRelationOffset(element, kind, node.offset, node.length);
+    }
+  }
+
+  /**
+   * Record that [element] has a relation of the given [kind] at the given
+   * [offset] and [length].
+   */
+  void recordRelationOffset(
+      Element element, IndexRelationKind kind, int offset, int length) {
+    // Ignore elements that can't be referenced outside of the unit.
+    if (element == null ||
+        element is LocalVariableElement ||
+        element is ParameterElement &&
+            element.parameterKind != ParameterKind.NAMED ||
+        element is FunctionElement &&
+            element.enclosingElement is ExecutableElement) {
+      return;
+    }
+    // Add the relation.
+    assembler.addRelation(element, kind, offset, length);
+  }
+
+  /**
+   * Record that [element] has a relation of the given [kind] at the location
+   * of the given [token].
+   */
+  void recordRelationToken(
+      Element element, IndexRelationKind kind, Token token) {
+    if (element != null && token != null) {
+      recordRelationOffset(element, kind, token.offset, token.length);
+    }
+  }
+
+  @override
+  visitAssignmentExpression(AssignmentExpression node) {
+    _recordOperatorReference(node.operator, node.bestElement);
+    super.visitAssignmentExpression(node);
+  }
+
+  @override
+  visitBinaryExpression(BinaryExpression node) {
+    _recordOperatorReference(node.operator, node.bestElement);
+    super.visitBinaryExpression(node);
+  }
+
+  @override
+  visitClassDeclaration(ClassDeclaration node) {
+    ClassElement element = node.element;
+    _recordTopLevelElementDefinition(element);
+    {
+      ExtendsClause extendsClause = node.extendsClause;
+      if (extendsClause != null) {
+        TypeName superclassNode = extendsClause.superclass;
+        _recordSuperType(superclassNode, IndexRelationKind.IS_EXTENDED_BY);
+      } else {
+        InterfaceType superType = element.supertype;
+        if (superType != null) {
+          ClassElement objectElement = superType.element;
+          recordRelationOffset(objectElement, IndexRelationKind.IS_EXTENDED_BY,
+              node.name.offset, 0);
+        }
+      }
+    }
+    {
+      WithClause withClause = node.withClause;
+      if (withClause != null) {
+        for (TypeName mixinNode in withClause.mixinTypes) {
+          _recordSuperType(mixinNode, IndexRelationKind.IS_MIXED_IN_BY);
+        }
+      }
+    }
+    {
+      ImplementsClause implementsClause = node.implementsClause;
+      if (implementsClause != null) {
+        for (TypeName interfaceNode in implementsClause.interfaces) {
+          _recordSuperType(interfaceNode, IndexRelationKind.IS_IMPLEMENTED_BY);
+        }
+      }
+    }
+    super.visitClassDeclaration(node);
+  }
+
+  @override
+  visitClassTypeAlias(ClassTypeAlias node) {
+    ClassElement element = node.element;

[Paul Berry, 2016/02/25 23:05:12]

There's a lot of common code between this method and the one above.  Consider
refactoring the common code into its own method.

[scheglov, 2016/02/26 04:54:02]

Done.

+    _recordTopLevelElementDefinition(element);
+    {
+      TypeName superclassNode = node.superclass;
+      if (superclassNode != null) {
+        _recordSuperType(superclassNode, IndexRelationKind.IS_EXTENDED_BY);
+      }
+    }
+    {
+      WithClause withClause = node.withClause;
+      if (withClause != null) {
+        for (TypeName mixinNode in withClause.mixinTypes) {
+          _recordSuperType(mixinNode, IndexRelationKind.IS_MIXED_IN_BY);
+        }
+      }
+    }
+    {
+      ImplementsClause implementsClause = node.implementsClause;
+      if (implementsClause != null) {
+        for (TypeName interfaceNode in implementsClause.interfaces) {
+          _recordSuperType(interfaceNode, IndexRelationKind.IS_IMPLEMENTED_BY);
+        }
+      }
+    }
+    super.visitClassTypeAlias(node);
+  }
+
+  @override
+  visitConstructorFieldInitializer(ConstructorFieldInitializer node) {
+    SimpleIdentifier fieldName = node.fieldName;
+    Expression expression = node.expression;
+    // field reference is write here

[Paul Berry, 2016/02/25 23:05:12]

I don't understand this comment.  Do you mean "right here" or "written here"?

[scheglov, 2016/02/26 04:54:03]

Initially the code was using IndexRelationKind.IS_WRITTEN_BY.
But then I removed IS_WRITTEN_BY altogether - it was mostly useful for local
variables and parameters, which we don't record into index anymore. And a field,
if we record it into index (this.field and constructor field initializer) is
always written. And in the most cases getter/setter elements are referenced, not
fields.

I removed the comment.

+    if (fieldName != null) {
+      Element element = fieldName.staticElement;
+      recordRelation(element, IndexRelationKind.IS_REFERENCED_BY, fieldName);
+    }
+    // index expression
+    if (expression != null) {
+      expression.accept(this);
+    }
+  }
+
+  @override
+  visitConstructorName(ConstructorName node) {
+    ConstructorElement element = node.staticElement;
+    // in 'class B = A;' actually A constructors are invoked
+    if (element != null &&
+        element.isSynthetic &&
+        element.redirectedConstructor != null) {
+      element = element.redirectedConstructor;

[Paul Berry, 2016/02/25 23:05:13]

What if there are multiple levels of indirection?

What if the indirections form a loop?

[scheglov, 2016/02/26 04:54:03]

I will add TODO and test/fix it in the next CL.

+    }
+    // record relation
+    if (node.name != null) {
+      int offset = node.period.offset;
+      int length = node.name.end - offset;
+      recordRelationOffset(
+          element, IndexRelationKind.IS_REFERENCED_BY, offset, length);
+    } else {
+      int offset = node.type.end;
+      recordRelationOffset(
+          element, IndexRelationKind.IS_REFERENCED_BY, offset, 0);
+    }
+    super.visitConstructorName(node);
+  }
+
+  @override
+  visitEnumDeclaration(EnumDeclaration node) {
+    ClassElement element = node.element;
+    _recordTopLevelElementDefinition(element);
+    super.visitEnumDeclaration(node);
+  }
+
+  @override
+  visitExportDirective(ExportDirective node) {
+    ExportElement element = node.element;
+    if (element != null) {
+      LibraryElement expLibrary = element.exportedLibrary;
+      _recordLibraryReference(node, expLibrary);
+    }
+    _recordUriFileReference(node);
+    super.visitExportDirective(node);
+  }
+
+  @override
+  visitFunctionDeclaration(FunctionDeclaration node) {
+    Element element = node.element;
+    _recordTopLevelElementDefinition(element);
+    super.visitFunctionDeclaration(node);
+  }
+
+  @override
+  visitFunctionTypeAlias(FunctionTypeAlias node) {
+    Element element = node.element;
+    _recordTopLevelElementDefinition(element);
+    super.visitFunctionTypeAlias(node);
+  }
+
+  @override
+  visitImportDirective(ImportDirective node) {
+    ImportElement element = node.element;
+    if (element != null) {
+      LibraryElement impLibrary = element.importedLibrary;
+      _recordLibraryReference(node, impLibrary);
+    }
+    _recordUriFileReference(node);
+    super.visitImportDirective(node);
+  }
+
+  @override
+  visitIndexExpression(IndexExpression node) {
+    MethodElement element = node.bestElement;
+    if (element is MethodElement) {
+      Token operator = node.leftBracket;
+      recordRelationToken(element, IndexRelationKind.IS_INVOKED_BY, operator);
+    }
+    super.visitIndexExpression(node);
+  }
+
+  @override
+  visitMethodInvocation(MethodInvocation node) {
+    SimpleIdentifier name = node.methodName;
+    // TODO(scheglov) do we need this?
+//    LocationImpl location = _createLocationForNode(name);
+//    // name invocation
+//    recordRelationshipIndexable(
+//        new IndexableName(name.name), IndexConstants.IS_INVOKED_BY, location);
+    // element invocation
+    Element element = name.bestElement;
+    if (element is MethodElement ||
+        element is PropertyAccessorElement ||
+        element is FunctionElement ||
+        element is VariableElement) {
+      recordRelation(element, IndexRelationKind.IS_INVOKED_BY, node);
+    } else if (element is ClassElement) {
+      recordRelation(element, IndexRelationKind.IS_REFERENCED_BY, node);
+    }
+    node.target?.accept(this);
+    node.argumentList?.accept(this);
+  }
+
+  @override
+  visitPartDirective(PartDirective node) {
+    recordRelation(node.element, IndexRelationKind.IS_REFERENCED_BY, node);
+    _recordUriFileReference(node);
+    super.visitPartDirective(node);
+  }
+
+  @override
+  visitPartOfDirective(PartOfDirective node) {
+    recordRelation(node.element, IndexRelationKind.IS_REFERENCED_BY, node);
+  }
+
+  @override
+  visitPostfixExpression(PostfixExpression node) {
+    _recordOperatorReference(node.operator, node.bestElement);
+    super.visitPostfixExpression(node);
+  }
+
+  @override
+  visitPrefixExpression(PrefixExpression node) {
+    _recordOperatorReference(node.operator, node.bestElement);
+    super.visitPrefixExpression(node);
+  }
+
+  @override
+  visitRedirectingConstructorInvocation(RedirectingConstructorInvocation node) {
+    ConstructorElement element = node.staticElement;
+    if (node.constructorName != null) {
+      int offset = node.period.offset;
+      int length = node.constructorName.end - offset;
+      recordRelationOffset(
+          element, IndexRelationKind.IS_REFERENCED_BY, offset, length);
+    } else {
+      int offset = node.thisKeyword.end;
+      recordRelationOffset(
+          element, IndexRelationKind.IS_REFERENCED_BY, offset, 0);
+    }
+    super.visitRedirectingConstructorInvocation(node);
+  }
+
+  @override
+  visitSimpleIdentifier(SimpleIdentifier node) {
+    // TODO(scheglov) do we need this?
+//    IndexableName indexableName = new IndexableName(node.name);
+//    LocationImpl location = _createLocationForNode(node);
+//    if (location == null) {
+//      return;
+//    }
+    // name in declaration
+    if (node.inDeclarationContext()) {
+      // TODO(scheglov) do we need this?
+//      recordRelationshipIndexable(
+//          indexableName, IndexConstants.NAME_IS_DEFINED_BY, location);
+      return;
+    }
+    // name in an extends/with/implements clause
+    if (_isInExtendsWithImplementsClause(node)) {
+      return;
+    }
+    Element element = node.bestElement;
+    // this.field parameter
+    if (element is FieldFormalParameterElement) {
+      recordRelation(element.field, IndexRelationKind.IS_REFERENCED_BY, node);
+      return;
+    }
+    // record specific relations
+    if (element is ClassElement ||
+        element is FunctionElement ||
+        element is FunctionTypeAliasElement ||
+        element is LabelElement ||
+        element is MethodElement ||
+        element is PropertyAccessorElement ||
+        element is PropertyInducingElement ||
+        element is TypeParameterElement) {
+      recordRelation(element, IndexRelationKind.IS_REFERENCED_BY, node);
+    } else if (element is PrefixElement) {

[Paul Berry, 2016/02/25 23:05:13]

This clause can be combined with the "if" clause above, since the bodies are the
same.

[scheglov, 2016/02/26 04:54:03]

Done.

+      recordRelation(element, IndexRelationKind.IS_REFERENCED_BY, node);
+    }
+    super.visitSimpleIdentifier(node);
+  }
+
+  @override
+  visitSuperConstructorInvocation(SuperConstructorInvocation node) {
+    ConstructorElement element = node.staticElement;
+    if (node.constructorName != null) {
+      int offset = node.period.offset;
+      int length = node.constructorName.end - offset;
+      recordRelationOffset(
+          element, IndexRelationKind.IS_REFERENCED_BY, offset, length);
+    } else {
+      int offset = node.superKeyword.end;
+      recordRelationOffset(
+          element, IndexRelationKind.IS_REFERENCED_BY, offset, 0);
+    }
+    super.visitSuperConstructorInvocation(node);
+  }
+
+  @override
+  visitVariableDeclaration(VariableDeclaration node) {
+    VariableElement element = node.element;
+    _recordTopLevelElementDefinition(element);
+    // TODO(scheglov) do we need this?
+//    // record declaration
+//    {
+//      SimpleIdentifier name = node.name;
+//      LocationImpl location = _createLocationForNode(name);
+//      location = _getLocationWithExpressionType(location, node.initializer);
+//      recordRelationshipElement(
+//          element, IndexConstants.NAME_IS_DEFINED_BY, location);
+//    }
+    super.visitVariableDeclaration(node);
+  }
+
+  /**
+   * Records reference to defining [CompilationUnitElement] of the given
+   * [LibraryElement].
+   */
+  void _recordLibraryReference(UriBasedDirective node, LibraryElement library) {

[Paul Berry, 2016/02/25 23:05:13]

All methods in this class are inherently private since the class is private. 
Consider renaming this to "recordLibraryReference" so that it sorts with the
other "record..." methods.

[scheglov, 2016/02/26 04:54:03]

Done.

+    recordRelation(library, IndexRelationKind.IS_REFERENCED_BY, node?.uri);
+  }
+
+  /**
+   * Record reference to the given operator [Element] and name.
+   */
+  void _recordOperatorReference(Token operator, Element element) {
+    recordRelationToken(element, IndexRelationKind.IS_INVOKED_BY, operator);
+    // TODO(scheglov) do we need this?
+//    // prepare location
+//    LocationImpl location = _createLocationForToken(operator, element != null);
+//    // record name reference
+//    {
+//      String name = operator.lexeme;
+//      if (name == "++") {
+//        name = "+";
+//      }
+//      if (name == "--") {
+//        name = "-";
+//      }
+//      if (StringUtilities.endsWithChar(name, 0x3D) && name != "==") {
+//        name = name.substring(0, name.length - 1);
+//      }
+//      IndexableName indexableName = new IndexableName(name);
+//      recordRelationshipIndexable(
+//          indexableName, IndexConstants.IS_INVOKED_BY, location);
+//    }
+//    // record element reference
+//    if (element != null) {
+//      recordRelationshipElement(
+//          element, IndexConstants.IS_INVOKED_BY, location);
+//    }
+  }
+
+  /**
+   * Records a relation between [superNode] and its [Element].
+   */
+  void _recordSuperType(TypeName superNode, IndexRelationKind kind) {
+    if (superNode != null) {
+      Identifier superName = superNode.name;
+      if (superName != null) {
+        Element superElement = superName.staticElement;
+        recordRelation(superElement, kind, superName);
+      }
+    }
+  }
+
+  /**
+   * Record the top-level [element] definition.
+   */
+  void _recordTopLevelElementDefinition(Element element) {
+    // TODO(scheglov) do we need this?
+//    if (element?.enclosingElement is CompilationUnitElement) {
+//      IndexableElement indexable = new IndexableElement(element);
+//      int offset = element.nameOffset;
+//      int length = element.nameLength;
+//      LocationImpl location = new LocationImpl(indexable, offset, length);
+//      recordRelationshipElement(
+//          _libraryElement, IndexConstants.DEFINES, location);
+//      _store.recordTopLevelDeclaration(element);
+//    }
+  }
+
+  void _recordUriFileReference(UriBasedDirective directive) {
+    Element element = directive.element;
+    recordRelation(element, IndexRelationKind.IS_REFERENCED_BY, directive.uri);
+  }
+
+  static bool _isInExtendsWithImplementsClause(SimpleIdentifier node) {
+    TypeName typeName;
+    AstNode parent = node?.parent;
+    AstNode parent2 = parent?.parent;
+    if (parent is TypeName && parent.name == node) {
+      typeName = parent;
+    } else if (parent is PrefixedIdentifier &&
+        parent.identifier == node &&
+        parent2 is TypeName &&
+        parent2.name == node) {
+      typeName = parent2;
+    } else {
+      return false;
+    }
+    AstNode clause = typeName.parent;
+    return clause is ExtendsClause ||
+        clause is WithClause ||
+        clause is ImplementsClause;
+  }
+}
+
+/**
+ * Information about a single relation.

[Paul Berry, 2016/02/25 23:05:12]

Add a comment explaining that [_RelationInfo] always exists inside of
[_UnitIndexAssembler.relations], so [offset] and [length] should be understood
within the context of the compilation unit pointed to by the
[_UnitIndexAssempler].

[scheglov, 2016/02/26 04:54:03]

Done.

+ */
+class _RelationInfo {
+  final _ElementInfo element;

[Paul Berry, 2016/02/25 23:05:13]

Rename to "elementInfo".  Otherwise it's easy to be confused when reading line
612 and incorrectly conclude that it's sorting by [Element.id].

[scheglov, 2016/02/26 04:54:03]

Done.

+  final IndexRelationKind kind;
+  final int offset;
+  final int length;
+
+  _RelationInfo(this.element, this.kind, this.offset, this.length);
+}
+
+/**
+ * Assembler of a single [CompilationUnit] index.
+ */

[Paul Berry, 2016/02/25 23:05:13]

As with [PackageIndexAssembler], it would be helpful to have a comment
explaining how this is intended to be used.  I *think* the intention is:
- Call [addRelation] for each relation found in the compilation unit.
- Assign ids to all the _ElementInfo objects reachable from [relations].
- Call [assemble] to produce the final unit index.

[scheglov, 2016/02/26 04:54:03]

Done.

+class _UnitIndexAssembler {
+  final PackageIndexAssembler pkg;
+  final CompilationUnitElement unitElement;
+  final List<_RelationInfo> relations = <_RelationInfo>[];
+
+  _UnitIndexAssembler(this.pkg, this.unitElement);
+
+  void addRelation(
+      Element element, IndexRelationKind kind, int offset, int length) {
+    _ElementInfo elementInfo = pkg._getElementInfo(element);
+    relations.add(new _RelationInfo(elementInfo, kind, offset, length));
+  }
+
+  /**
+   * Assemble a new [UnitIndexBuilder] using the gathered information.

[Paul Berry, 2016/02/25 23:05:12]

s/using the gathered information/using the information gathered by
[addRelation]/

[scheglov, 2016/02/26 04:54:03]

Done.

+   */
+  UnitIndexBuilder assemble() {
+    relations.sort((a, b) {
+      return a.element.id - b.element.id;
+    });
+    return new UnitIndexBuilder(
+        elements: relations.map((r) => r.element.id).toList(),
+        kinds: relations.map((r) => r.kind).toList(),
+        locationOffsets: relations.map((r) => r.offset).toList(),
+        locationLengths: relations.map((r) => r.length).toList(),
+        libraryUri: pkg._getUriId(unitElement.library.source.uri),
+        unitUri: pkg._getUriId(unitElement.source.uri));
+  }
+}