for contributors (must read)

[hex13]

**PROJECT IS CURRENTLY IN MAINTENANCE ONLY MODE. ONLY BUG FIXES ANS SMALL IMPROVEMENTS. READ WHOLE THREAD***

Overview and purpose of the project Lupa will read text files (JS, HTML, CSS etc.) and will use various means to analyses these (i.e. regexps, AST, code running etc.). It is supposed to have plugin-based architecture. Every plugin (file reader) will process file(input) and return(output) plain javascript object in specific format. This data will be integrated elsewhere in project (plugin shouldn't know anything about such an integration. Plugin has to just process input and return output).

Then integrated data will be transformed appropriately (it will be configurable which transformations should be used)

Then transformed data will be send to the reporter/view and presented to user in, for example, form of animated diagram (using HTML/JS and libraries like D3.js) representing dependencies between modules. Or tree with all found classes/objects/modules in object and some form metadata attached to it, e.g. property/method names for each class. Maybe some code excerpts (usage examples for example). This project is supposed to help programmers in better understanding of their projects.

General program flow will be: --> Get Project Configuration (for example directory structure patterns, list of plugins etc.) --> Analyse Files (plugins will be doing that) --> Transform Data --> Create output / code visualisation / report and return to user

Planned architecture will look like that:

• some method of project configuration
• plugins for reading analyse files.
• transformations/mappers to modify raw data into something more appropriate (for example making trees or graphs from plain old arrays).
• reporters/views - modules that will be responsible for creating output. e.g. rendering HTML from template and inject data in it.

for now it is preparatory phase. EVERYTHING COULD CHANGE. I made this project public but I need time for prepare Lupa's architecture so that contributions from other developers than me would make any sense (I think that I need few weeks of alone work on this project). Then there should be more established architecture and potential merging will be a lot easier.

(Maybe this all writing is purposeless. Maybe I will be one solely developer working on that. And maybe nobody will join and contribute... But I think that this whole project idea has great sense and sooner or later somebody will stumble on it and try to submit his/her pull request)

[hex13]

Current architecture/implementation:

• analysis object which exposes API for analysis.

• plugins for analysing. Every plugin gets virtual file object as a first argument. This file object has ast property. Then plugin should return Rx observable which would emit copy of file object enriched with metadata. - altough you can't assume that in the future versions Rx would be used at all. You should rather suppose that your plugin takes file object as a argument and return results via some sort of callback. Current using of Rx is just implementation detail. So you would better split your plugin on two files: one written in Vanilla JS and second which be wrapper for current implementation in Rx. Check for example this: https://github.com/hex13/lupa/blob/master/plugins/javascript.js there is no Rx at all in this plugin. It's just glued later to work with Rx in analysis.js

  file object has such structure (it extends vinyl file object: https://github.com/gulpjs/vinyl )

{
   // properties from Vinyl file objects
   path: '.......',.
   contents: new Buffer('......')

   ast: {....} // parsed AST,

   metadata: [
       {type: 'function', name: 'onClick'},
       {type: 'function', name: 'onMouseOver'},
   ] // array with metadata
}

Because mutable state easily can cause many bugs (been there, done that) and the test coverage is mediocre #9, plugins should treat file objects as immutable objects (i.e. clone objects instead of changing in-place).

But do not use file.clone() because it would copy whole buffer (tried that and it was very slow. Use helper like Metadata.addMetadata here (example plugin): https://github.com/hex13/lupa/blob/master/plugins/coffeescript.js

And notice that API is still unstable and probably many things change in the near future.

There are also some trade outs - cloning objects can take time and be memory costly. So maybe it would be better to consider some in-place mutable modifing but in the safe way? (mutability is not always bad).

And many things are not here yet. The project was rewritten from scratch few times. It took time. But now it's time to stabilize this whole thing.

[hex13]

Project is in maintenance only mode. I will fix potential bugs or make some slight improvements - but overally I've started already a new project which will be alternative to Lupa (it will allow for more detailed analysis than Lupa currently does).

So soon Lupa can either be deprecated or just rewritten (actually I'm rewriting from scratch all features, but I don't know if I will name new library e.g. Lupa 2 or create whole new name).