docs: add comments and legal notice to readme

Author: 1egoman

README.md

@@ -1,15 +1,14 @@
 # debundle
 
 This is a tool to decode javascript bundles produced by tools like [Webpack](https://webpack.github.io/) and [Browserify](http://browserify.org/)
-into their original, pre-bunded source.
+into their original, pre-bundled source.
 
 [![Build Status](https://travis-ci.org/1egoman/debundler.svg?branch=master)](https://travis-ci.org/1egoman/debundler)
 
 ## Why would I want to debundle my code?
-Reasons vary, but I originally developed this to help me with a reverse engineering project I was
-working on. Needless to say, sifting through minified bundles to try and figure out how a service
-works isn't fun and is a lot easier when that bundle is broken into files and those files have
-semantic names. 
+Reasons vary, but this tool was originally developed to help me with a reverse engineering project.
+Needless to say, sifting through minified bundles to try and figure out how a service works isn't
+fun and is a lot easier when that bundle is broken into files and those files have semantic names. 
 
 ## Installation
 ```
@@ -95,8 +94,14 @@ This is indicated as an array of strings / numbers used to traverse through the
 For example, `["foo", "bar", 0, "baz", 1]` would get `ast.foo.bar[0].baz[1]`.
 
 # Contributing
+- After cloning down the project, run `npm install` - that should be it.
 - Debundler entry point is `./src/index.js` (that's how you run it!)
 - A bunch of sample bundles are in `test_bundles/`. A script, `test_bundles/run_test.sh` can run the
   debundler against a given bundle and try to debundle it into `dist/`. (CI will, as part of running
   tests, debundle all the bundles in that folder.)
-- Make sure any contribution passes the tests: `npm test`
+- Make sure any contribution pass the tests: `npm test`
+
+# Legal note
+Some companies specify in their terms of service that their code cannot be "reverse engineered".
+Debundling can definitely (depending on how you're using the code) fall under that umbrella.
+Understand what you are doing so you don't break any agreements :smile:

src/index.js

@@ -6,6 +6,10 @@ const inquirer = require('inquirer');
 const args = require('minimist')(process.argv.slice(2));
 const convertToIntegerKey = require('./utils/convertToIntegerKey');
 
+// ----------------------------------------------------------------------------
+// Set up configuration
+// ----------------------------------------------------------------------------
+
 const bundleLocation = args._[0] || args.input || args.i;
 const outputLocation = args.output || args.o;
 const configPath = args.config || args.c;
@@ -42,7 +46,9 @@ if (!config.moduleAst) {
   console.log(`* Using default AST location for ${config.type}...`);
 }
 
-
+// ----------------------------------------------------------------------------
+// Read in bundle
+// ----------------------------------------------------------------------------
 
 console.log('* Reading bundle...');
 const bundleContents = fs.readFileSync(bundleLocation);
@@ -60,17 +66,9 @@ if (config.entryPoint === undefined) {
 }
 
 
-
-
-// TODO
-// KNOWN BUGS
-// - If a package has a nonstandard location for it's root file (ie, not in index.js), and that
-// location is in a folder, then we aren't smart enough to put that in the right location.
-// ie, blueprint has it's root in `src/index.js` and it requires `./common` from that file, which
-// when the root file is put in `index.js` it can't resolve.
-
-// Browserify bundles start with an IIFE. Fetch the IIFE and get it's arguments (what we care about,
-// and where all the module code is located)
+// ----------------------------------------------------------------------------
+// Find all the modules in the bundle via `moduleAst`
+// ----------------------------------------------------------------------------
 
 let iifeModules = ast;
 while (true) {
@@ -84,18 +82,10 @@ while (true) {
   }
 }
 
-// Known paths are inserted absolutely into requires. They need to be made relative.
-//
-
-
-
-// Webpack bundle
-// let iifeModules = ast.body[0].expression.arguments[0];
-
-
-
-
-
+// ------------------------------------------------------------------------------
+// Given the path to the modules in the AST and the AST, pull out the modules and normalize
+// them to a predefined format.
+// ------------------------------------------------------------------------------
 
 console.log('* Decoding modules...');
 
@@ -110,14 +100,22 @@ if (config.type === 'browserify') {
   modules = webpackDecoder(iifeModules, config.knownPaths);
 }
 
+
+
+// ------------------------------------------------------------------------------
 // Transform the module id in each require call into a relative path to the module.
 // var a = require(1) => var a = require('./path/to/a')
+// ------------------------------------------------------------------------------
+
 console.log('* Reassembling requires...');
 const transformRequires = require('./transformRequires');
 modules = transformRequires(modules, config.knownPaths, config.entryPoint, config.type);
 
+// ------------------------------------------------------------------------------
 // Take the array of modules and figure out where to put each module on disk.
 // module 1 => ./dist/path/to/a.js
+// ------------------------------------------------------------------------------
+
 console.log('* Resolving files...');
 const lookupTableResolver = require('./lookupTable');
 const files = lookupTableResolver(
@@ -128,6 +126,9 @@ const files = lookupTableResolver(
   outputLocation
 );
 
+// ------------------------------------------------------------------------------
+// Finally, write the bundle to disk in the specified output location.
+// ------------------------------------------------------------------------------
 
 console.log('* Writing to disk...');
 const writeToDisk = require('./writeToDisk');

test_bundles/webpack-with-known-paths/debundle.config.json.bkp

@@ -1,12 +1,9 @@
 {
   "type": "webpack",
+  "entryPoint": 8,
   "knownPaths": {
-    "216": "@blueprintjs/core/src/components",
-    "73": "./blah/querystring",
-    "70": "./foo/somethingThatImportsQuerystring",
-
-    "90": "uuid/v1",
-    "91": "uuid/rng",
-    "92": "uuid/bytesToUuid"
+    "8": "./index",
+    "4": "./foo",
+    "0": "uuid"
   }
 }