add tool to verify dependency information

README.md

 # Dart2js Info
 
 This package contains libraries and tools you can use to process `.info.json`
 files, which are produced when running dart2js with `--dump-info`.
 
 The `.info.json` files contain data about each element included in
 the output of your program. The data includes information such as:
 
   * the size that each function adds to the `.dart.js` output,
   * dependencies between functions,
   * how the code is clustered when using deferred libraries, and
   * the declared and inferred type of each function argument.
 
 All of this information can help you understand why some piece of code is
 included in your compiled application, and how far was dart2js able to
 understand your code. This data can help you make changes to improve the quality
 and size of your framework or app.
 
 This package focuses on gathering libraries and tools that summarize all of that
 information. Bear in mind that even with all these tools, it is not trivial to
 isolate code-size issues. We just hope that these tools make things a bit
-earier.
+easier.
 
 ## Status
 
 [![Build Status](https://travis-ci.org/dart-lang/dart2js_info.svg)](https://travis-ci.org/dart-lang/dart2js_info)
 
 Currently, most tools available here can be used to analyze code-size and
-attibution of code-size to different parts of your app. With time, we hope to
+attribution of code-size to different parts of your app. With time, we hope to
 add more data to the `.info.json` files, and include better tools to help
 understand the results of type inference.
 
 This package is still in flux and we might make breaking changes at any time.
 Our current goal is not to provide a stable API, we mainly want to expose the
 functionality and iterate on it.  We recommend that you pin a specific version
 of this package and update when needed.
 
 ## Info API
 
 [AllInfo][AllInfo] exposes a Dart representation of the `.info.json` files.
-You can parse the information using `AllInfo.parseFromJson`. For example:
+You can parse the information using `AllInfo.fromJson`. For example:
 
 ```dart
 import 'dart:convert';
 import 'dart:io';
 
 import 'package:dart2js_info/info.dart';
 
 main(args) {
   var infoPath = args[0];
   var json = JSON.decode(new File(infoPath).readAsStringSync());
-  var info = AllInfo.parseFromJson(json);
+  var info = new AllInfo.fromJson(json);
   ...
+}
 ```
 
 ## Available tools
 
 The following tools are a available today:
 
   * [`code_deps.dart`][code_deps]: simple tool that can answer queries about the
     dependency between functions and fields in your program. Currently it only
     supports the `some_path` query, which shows a dependency path from one
     function to another.
 
   * [`library_size_split`][lib_split]: a tool that shows how much code was
     attributed to each library. This tool is configurable so it can group data
     in many ways (e.g. to tally together all libraries that belong to a package,
     or all libraries that match certain name pattern).
 
   * [`function_size_analysis`][function_analysis]: a tool that shows how much
-    code was attributed to each function. This tool also uses depedency
+    code was attributed to each function. This tool also uses dependency
     information to compute dominance and reachability data. This information can
     sometimes help determine how much savings could come if the function was not
     included in the program.
 
   * [`coverage_log_server`][coverage] and [`live_code_size_analysis`][live]:
     dart2js has an experimental feature to gather coverage data of your
     application. The `coverage_log_server` can record this data, and
     `live_code_size_analysis` can correlate that with the `.info.json`, so you
     determine why code that is not used is being included in your app.
 
+  * [`verify_deps`][verify_deps]: a tool that verifies that all elements are
+    reachable from the program's entrypoint. If there are unreachable elements,
+    this indicates that the dependency information is incomplete.
+
 Next we describe in detail how to use each of these tools.
 
 ### Code deps tool
 
 This command-line tool can be used to query for code dependencies. Currently
 this tool only supports the `some_path` query, which gives you the shortest path
 for how one function depends on another.
 
 Run this tool as follows:
 ```bash
@@ skipping 85 matching lines @@
 # If your code lives under /my/project/dir, this will match any file loaded
 from a file:// url, and we use as a name the relative path to it.
 - regexp: "file:///my/project/dir/(.*)"
 ```
 
 Regardless of the grouping configuration, the tool will display the total code
 size attributed of all libraries, constants, and the program size.
 
 **Note**: eventually you should expect all numbers to add up to the program
 size. Currently dart2js's `--dump-info` is not complete, so numbers for
-bootstraping code and lazy static initializers are missing.
+bootstrapping code and lazy static initializers are missing.

[Siggi Cherem (dart-lang), 2015/10/14 23:37:02]

thanks for all the typo fixes!

[Harry Terkelsen, 2015/10/15 00:13:55]

no problem :)

 
 ### Function size analysis tool
 
 This command-line tool presents how much each function contributes to the total
 code of your application.  We use dependency information to compute dominance
 and reachability data as well.
 
 When you run:
 ```bash
 pub global activate dart2js_info # only needed once
@@ skipping 46 matching lines @@
     html file or integrate your application server to proxy to the log server
     any GET request for the .dart.js file and /coverage POST requests that send
     coverage data.
 
   * Load your app and use it to exercise the entire code.
 
   * Shut down the coverage server (Ctrl-C). This will emit a file named
     `mail.dart.js.coverage.json`
 
   * Finally, run the live code analysis tool given it both the info and
-    converage json files:
+    coverage json files:
 
 ```bash
 dart2js_info_live_code_size_analysis main.dart.info.json main.dart.coverage.json
 ```
 
+### Verifying dependencies
+
+Coverage of dependency information may be incomplete. If there are elements that
+are live in the output that are unreachable through dependencies from the
+program's entrypoint, then we have incomplete dependency information. Note,
+however, that all elements may be reachable from the entrypoint even if there
+is missing dependency information. In order to verify that all elements are
+reachable from the app's entrypoint, simply run the tool as so:
+
+```bash
+dart2js_info_verify_deps foo.info.json
+```
+
+If all elements are reachable from the entrypoint, then the tool will not
+output anything and will return with exitcode 0. Otherwise, the tool will

[Siggi Cherem (dart-lang), 2015/10/14 23:37:02]

sometimes not seeing any results feels like a mystery. How about we print a
single line saying "everything appears reachable" or something similar?

[Harry Terkelsen, 2015/10/15 00:13:55]

Done.

+output the list of all functions that are not reachable from the entrypoint
+and return with exitcode 1.
+
 ## Code location, features and bugs
 
 This package is developed in [github][repo].  Please file feature requests and
 bugs at the [issue tracker][tracker].
 
 [repo]: https://github.com/dart-lang/dart2js_info/
 [tracker]: https://github.com/dart-lang/dart2js_info/issues
 [code_deps]: https://github.com/dart-lang/dart2js_info/blob/master/bin/code_deps.dart
 [lib_split]: https://github.com/dart-lang/dart2js_info/blob/master/bin/library_size_split.dart
 [coverage]: https://github.com/dart-lang/dart2js_info/blob/master/bin/coverage_log_server.dart
 [live]: https://github.com/dart-lang/dart2js_info/blob/master/bin/live_code_size_analysis.dart
 [function_analysis]: https://github.com/dart-lang/dart2js_info/blob/master/bin/function_size_analysis.dart
+[verify_deps]: https://github.com/dart-lang/dart2js_info/blob/master/bin/verify_deps.dart
 [AllInfo]: http://dart-lang.github.io/dart2js_info/doc/api/dart2js_info.info/AllInfo-class.html