Logging output-style report generation

[bllanos]

Requested reviewers: None Issues: #1

Summary of Changes

• Added a class for outputting the usage events of the object being watched in the order in which they occurred.
• Added a class for outputting counts of usage events grouped by property path or by type of event.

  Detailed Changes

  Time series of events

• Implemented by src/report/reporters/logStyleReporter.coffee
• The report output appears as follows:

Tick      Event      Path     (new) property value
13        changed    a.c.d    5
12        accessed   a.c      [object Object]
11        accessed   a.c.d    2
10        accessed   a        [object Object]
9         accessed   a.c.d    2
8         accessed   a.c      [object Object]
7         accessed   a.c.d    2
6         accessed   a.b      4
5         changed    a.b      4
4         accessed   a        [object Object]
3         accessed   a.c.d    2
2         accessed   a.c      [object Object]
1         accessed   a.b      3
0         accessed   a        [object Object]

Counts of events

• Implemented by src/report/reporters/eventCountsReporter.coffee
• Report output appears as follows:

Event: accessed
    Path     Count
    a        3
    a.b      2
    a.c      3
    a.c.d    4
Event: added
    Path     Count
Event: changed
    Path     Count
    a.b      1
    a.c.d    1
Event: removed
    Path     Count

• The report can also be grouped first by property path, then by event type.
• If the data is output grouped first by event type, properties can be sorted by path or by count of events.

  Infrastructure changes and bug fixes

• All report generators ('reporters') are child classes of the Reporter class (src/report/reporter.coffee) in an attempt to provide a standard interface.
• Both types of reports rely on src/report/common/flattenEvents.coffee to convert observation data returned by an ObservationStoreManager into a flat list of events. The flattening process adds property path data and an event type name to each event.
• The library provides access to Reporter objects through src/report/index.coffee, which serves as a factory.
• Corrected the ObservationStore and ObservationStoreManager classes so that they store data in a properly recursive structure. (Originally, the recursion depth was accidentally limited to one level, which could not accommodate observation data for properties of properties and deeper levels of nesting.)
• Observation data output and report generation is asynchronous (using promises).
  • In my opinion, the format in which observation data is stored allows for efficient insertion of observation data. However, formatting the data into a report is made more difficult/expensive by this format.
  • Note that the retrieval of observation data involves cloning. This protects stored observation data from accidental modification.

    Testing Performed

• Validated that the report output matched the debugging logger output of the property accessor functions bound to the wrapper object.
• Tested all combinations of report generation options (the options object passed to getReportAsString() in src/report/reporter.coffee.