Initial API for the Dart front_end package.

pkg/front_end/lib/resolved_ast_generator.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.
+
+/// Defines a front-end API for converting source code to resolved ASTs.
+///
+/// Note: this entire library is deprecated.  It is provided as a migration path
+/// until dev_compiler supports Dart Kernel.  Once dev_compiler has been
+/// converted to use Dart Kernel, this functionality will be removed.
+@deprecated
+library front_end.resolved_ast_generator;
+
+import 'dart:async';
+import 'options.dart';
+import 'package:analyzer/dart/ast/ast.dart' show CompilationUnit;
+import 'package:analyzer/dart/element/element.dart' show LibraryElement;
+
+/// Processes the build unit whose source files are in [sources].
+///
+/// Intended for modular compilation.
+///
+/// [sources] should be the complete set of source files for a build unit
+/// (including both library and part files).  All of the library files are
+/// compiled to Dart Kernel objects.

[scheglov, 2016/10/16 21:19:39]

I think we don't produce Kernel objects here.

[Paul Berry, 2016/10/17 12:54:39]

Fixed, thanks.

+///
+/// The compilation process is hermetic, meaning that the only files which will
+/// be read are those listed in [sources], [Options.inputSummaries], and
+/// [Options.sdkSummary].  If a source file attempts to refer to a file which is
+/// not obtainable from these paths, that will result in an error, even if the
+/// file exists on the filesystem.
+///
+/// Any `part` declarations found in [sources] must refer to part files which
+/// are also listed in [sources], otherwise an error results.  (It is not
+/// permitted to refer to a part file declared in another build unit).

[scheglov, 2016/10/16 21:19:39]

I think we have already told about library and part files in the third
paragraph.

[Paul Berry, 2016/10/17 12:54:39]

Acknowledged.  However, as I read it, the third paragraph merely says that both
the library and part files for a given build unit must be specified in
[sources].  It doesn't say that a library file and the part file it refers to
must be located in the same build unit.  I want to be very clear about that
difference, because IIRC that's currently a difference in behavior between
analyzer summary generation and dev_compiler.

+@deprecated
+Future<ResolvedAsts> resolveBuildUnit(Options options, List<Uri> sources) =>
+    throw new UnimplementedError();
+
+/// Representation of the resolved ASTs of a build unit.
+@deprecated
+abstract class ResolvedAsts {
+  /// The resolved ASTs of the build unit's source libraries.
+  ///
+  /// There is one sub-list per source library; each sub-list consists of the
+  /// resolved AST for the library's defining compilation unit, followed by the
+  /// resolved ASTs for any of the library's part files.
+  final List<List<CompilationUnit>> compilationUnits;
+
+  /// Given a [LibraryElement] referred to by [compilationUnits], determine the
+  /// path to the summary that the library originated from.  If the
+  /// [LibraryElement] did not originate from a summary (i.e. because it
+  /// originated from one of the source files of *this* build unit), return
+  /// `null`.
+  ///
+  /// This can be used by the client to determine which build unit any
+  /// referenced element originated from.
+  String getOriginatingSummary(LibraryElement element);
+}