for contributors (must read) about lupa HOT 2 OPEN

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.

from lupa.

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).

from lupa.