codecrumbs 
What · Demo · Get started · Features · Case studies · Support · Contribute
What
Have you ever got lost in a big or unknown codebase? This tool will help you to solve that, as well as increase your development speed and quality of application architecture you build.
How it works? You run
codecrumbscommand for a codebase, it analyzes source code and build its visual representation. Put a codecrumb-comment and codebase state will be reflected by visual client in browser on the fly.
Demo
Check out standalone version running here with defined trail of codecrumbs.
Get started
Install and run
Pre-condition: update/install
NodeJSversion to be >= 8.11.1
Install codecrumbs globally or in devDependencies:
yarn add codecrumbs -D
Add command with entry file and source directory to scripts section in your package.json. Change -e (entry point file), -d (directory) params to match paths inside your project.
// package.json
...
"scripts": {
"start:cc": "codecrumbs -e src/index.js -d src"
}
Run yarn start:cc from the terminal. Go to http://localhost:2018/# in the browser to check it out.
CLI
-- TBD --
Features
Breadcrumbs
Write //cc:here is breadcrumb to put a simple breadcrumb in the code. cc (stands for "codecrumb") is the prefix which used by the parser, and here is breadcrumb is a title of our first breadcrumb.
Note: current version supports single line comments only.
Trail of breadcrumbs
Also, you can create “trail of breadcrumbs” — basically, a sequence of codecrumbs which follow some data flow (e.g. user login, or form submit, etc.).
To create a codecrumb as part of a trail you write: //cc:signin#3;enable route where signin is the trail ID, #3 is order number of step, enable route is a title describing the step.
Multi-codebase integration
You might be interested to study connections between several codebases (sub-modules), codecrumbs supports that. Simply start codecrumbs multiple times (once for each codebase), it all will be synced in one picture inside the browser tab.
E.g. for server-client application, go to the source directory for your server code and run codecrumbs -e your-server-src/index.py -d your-server-src, same for client codecrumbs -e src-client/index.js -d src-client. Note: codebases can be located wherever you want, simply run codecrumbs for directory you need.
Multi-language support
Current version supports next programming languages: javascript, typescript, python, php, java, c++ (and others which use // as a comment :)). Please file an issue to support other language you would like to have.
Note: In current version only JavaScript uses AST parser to process the code, hence it offers more features (e.g. Dependencies tree)
Export & import (learn and share your knowledge)
So let’s say you put together some trail of codecrumbs describing some important flow inside the project. How you can share it with others? Simply download the json file of codecrumbs store, send it to the friend, he/she uploads it to the codecrumbs and can see same you just saw!
Case studies
The tool (codecrumbs) allows us to learn, document and explain a codebase much faster. The ultimate goal is to have many case studies hosting at https://codecrumbs.io. The library of projects "explained with codecrumbs", the place for collaborative learning. More features around that coming soon, stay tuned.
Support
Any support is very much appreciated! 👍 😘 ❤️
Sponsors: contact me if you want to become a sponsor ☺️
Friends: if you like this project, please, put a ⭐ or tweet about it. Thanks!
Contribute
When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owner of this repository before making a change. Ideas and suggestions are welcome. To start development environment, clone the repo & run:
yarn && yarn start
WIP
Next features are developing:
- eject codecrumbs - ability to remove all "breadcrumbs" from source code in "one click"
- VS Code extension - some neat features right inside the code editor. Checkout the repo here.