add introspection and command to generate report

[t9md]

This PR introduce new generate-introspection-report command which generate introspection report as markdown format to untitled buffer.

• sample output

This is not enhancement to Vim feature, this introspection command sometime useful for vim-mode developer to get overview of each TextObject, Operator, Motion.

This introspection parse Function.toString() to find instance variable assignment and super call.
Not 100% accurate(parsing JavaScript function written in CoffeScript), but useful.

[jacekkopecky]

Cool! The generic reflection part feels like it could even be a separate NPM package. Please add a date to the generated report, and vim-mode package version, and if possible also current git commit ID, so it's easy to see if the report is up to date. Would it be possible/useful to output as the first part a subclass tree rather than an unordered list of subclass relationships?

[t9md]

Please add a date to the generated report, and vim-mode package version,
and if possible also current git commit ID, so it's easy to see if the
report is up to date.

Will do, I'm not sure for git commit ID, will try.
Currently the generated file will written to under ~/github/vim-mode/docs, which will convenient to update docs without moving file.
But if we add time, version, and commit ID, we'd better to write generated file to temporary file.

Would it be possible/useful to output as the first part a subclass tree
rather than an unordered list of subclass relationships?

I couldn't understand above, how does it like? I want some example.

[t9md]

Now removed TOM-report.md itself from docs/ dir. since its now written under tmpdir.
If maintainer need to include report, he need to manually move under docs.

By the way, if this reflection utility be merged, I can add realtime opStack observation feature.
Its also helpful to new developer understand how vim-mode works whey they try to add new TOM.

[jacekkopecky]

Regarding hierarchy: currently, your output is

• Input
• OperatorError
• Operator
• OperatorWithInput < Operator
• Select < Operator
• Delete < Operator

and I think it would be useful to have it sorted alphabetically and nested by subclassing like this

• Input
• Operator
  • Delete
  • Increase
    • Decrease
  • Join
  • LowerCase
  • OperatorWithInput
    • Mark
  • Repeat

[jacekkopecky]

The more and more I'm looking at this, the more it looks like it could be an Atom package independent of vim-mode, which would take the current project's coffee files and run this type of introspection on their exports.

Also, instead of generating a file, how about opening a new text editor and putting the content there? Then the user can choose where to save it, if at all.

[t9md]

Its good idea to save non-named buiffer and let user choose where to save.
For orders hiararchy its possible but I don't have such motivation currently.

The independend Package idea is good, maybe me or other person introduce in future.

My motivation is to introduce opStack ovservation feature on top of this introspection helper utility function to help developer.

Its already very useful to understand where to be fixed while refactoring in my refactor ecoeriment. I can directly spot what class operator is operate on when some operator throw error.

[t9md]

Updated first comment to fit to current implementation.

Here is the summary of change from first PR.

• Change command name generate-reflection-report to generate-introspection-report.
• Now table of content reflect inheritance hierarchy.
• Most of code moved from vim-state.cofee to introspection.coffee.

[maxbrunsfeld]

This is a really cool technique, but I don't think this code belongs inside of vim-mode. Maybe it should be a separate npm module, like @jacekkopecky said. It could be an executable, for example, that you run with any given node.js code, like this:

$ generate-introspection-report ~/.atom/packages/vim-mode/lib/*.coffee

[t9md]

Your example seem that command is executed separate process to statically analyze coffee source.
But my code is for dynamically introspect within vim-mode.

The main purpose of this addition is to add osStack observation(=debugging) feature to vim-mode on top of this introspection function.
Here is the example output of opStack observation and explanation of how operation stack works.
How Operation Stack works(for current official vim-mode)

Its very useful to developer adding or refactoring vim-mode.

Also this introspection report can be used to explain overall change between large commit by comparing to past report.
Here is example when I removed MotionWithInput intermediate class in my vim-mode folk.