pkg/vm_service_client: add getSourceReport to VMServiceReference

lib/src/source_report.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 'script.dart';
+import 'scope.dart';
+import 'source_location.dart';
+
+VMSourceReport newSourceReport(Scope scope, Map json) {
+  if (json == null) return null;
+  assert(json["type"] == "SourceReport");
+
+  var scripts = (json['scripts'] as List)
+      .map((script) => newVMScriptRef(scope, script))
+      .toList();
+
+  var ranges = new List<VMSourceReportRange>.unmodifiable(
+      (json['ranges'] as List).map((rangeItem) =>
+          new VMSourceReportRange._fromJson(rangeItem, scripts)));
+
+  return new VMSourceReport._(ranges);
+}
+
+/// A report about ranges of source code.
+///
+/// [ranges] exposes code coverage and information on possible breakpoints.
+class VMSourceReport {
+  /// Ranges in the program source corresponding to ranges of executable code in
+  /// the user's program.
+  ///
+  /// Ranges can include members such as functions, methods, and
+  /// constructors.
+  ///
+  /// Note: ranges may nest in other ranges, in the case of nested functions.
+  /// Rranges may be duplicated, in the case of mixins.

[nweiz, 2016/05/11 23:03:31]

"Rranges" -> "Ranges"

[kevmoo, 2016/05/12 05:22:34]

Done.

+  final List<VMSourceReportRange> ranges;
+
+  VMSourceReport._(this.ranges);
+}
+
+/// A range of executable code (function, method, constructor, etc)
+/// in the running program.
+///
+/// This is part of a [VMSourceReport].
+class VMSourceReportRange {
+  VMScriptRef get script => location.script;
+
+  /// The location of the range in the target script.
+  final VMSourceLocation location;
+
+  /// `true` if this range been compiled by the Dart VM.
+  ///
+  /// If `false`, `possibleBreakpoints`, `hits`, and `misses` will be `null`.
+  ///
+  /// Use `forceCompile` in `getSourceReport` to ensure the target scripts are
+  /// compiled.
+  final bool compiled;
+
+  /// Token positions at which breakpoints can be set.
+  ///
+  /// Provided only when `includePossibleBreakpoints` in `getSourceReport`
+  /// is `true` and the range has been compiled.
+  final List<VMScriptToken> possibleBreakpoints;
+
+  /// Token positions in a [VMSourceReportRange] which have been executed.

[nweiz, 2016/05/11 23:03:31]

"a [VMSourceReportRange]" -> "this range"

same below

[kevmoo, 2016/05/12 05:22:35]

Done.

+  ///
+  /// Provided only when `includeCoverageReport` in `getSourceReport` is `true`
+  /// and the range has been compiled.
+  ///
+  /// Sorted by the position in the source file, starting with the first hit.
+  final List<VMScriptToken> hits;
+
+  /// Token positions in a [VMSourceReportRange] which have not yet been
+  /// executed.
+  ///
+  /// Provided only when `includeCoverageReport` in `getSourceReport` is `true`
+  /// and the range has been compiled.
+  ///
+  /// Sorted by the location in the source file, starting with the first miss.
+  final List<VMScriptToken> misses;
+
+  factory VMSourceReportRange._fromJson(Map json, List<VMScriptRef> scripts) {

[nweiz, 2016/05/11 23:03:31]

Document this.

[kevmoo, 2016/05/12 05:22:35]

Done.

+    var script = scripts[json['scriptIndex']];
+
+    var location = newVMSourceLocationFromPosition(
+        script, json['startPos'], json['endPos']);
+
+    var compiled = json['compiled'];
+
+    var hits = json['coverage'] == null
+        ? null
+        : _getTokens(script, json['coverage']['hits']);
+
+    var misses = json['coverage'] == null
+        ? null
+        : _getTokens(script, json['coverage']['misses']);
+
+    var possibleBreakpoints = json['possibleBreakpoints'] == null
+        ? null
+        : _getTokens(script, json['possibleBreakpoints']);
+
+    return new VMSourceReportRange._(
+        compiled, hits, misses, possibleBreakpoints, location);
+  }
+
+  VMSourceReportRange._(this.compiled, this.hits, this.misses,
+      this.possibleBreakpoints, this.location);
+
+  static List<VMScriptToken> _getTokens(

[nweiz, 2016/05/11 23:03:31]

Document this as well.

[kevmoo, 2016/05/12 05:22:35]

Done.

+      VMScriptRef script, Iterable<int> locations) {
+    if (locations == null) return null;

[nweiz, 2016/05/11 23:03:31]

It shouldn't be possible for this to be null. It's not listed as optional in the
documentation. Have you seen it be null in your testing?

[kevmoo, 2016/05/12 05:22:35]

Acknowledged.

+
+    return new List<VMScriptToken>.unmodifiable(locations
+        .map((position) => newVMScriptTokenFromPosition(script, position)));
+  }
+}