Update README.md

WIP: feat: added codecrumbs.config

.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

.gitignore

@@ -3,7 +3,7 @@ node_modules
 
 # Build directories
 src/public/dist/local/bundle/
-src/public/dist/standalone/bundle/
+build/
 
 # example for dev
 # example-project

.npmignore

@@ -1,3 +1,5 @@
 .idea
 example-project
 docs
+src/public/js
+build

Dockerfile

@@ -0,0 +1,11 @@
+FROM node:14-slim
+
+WORKDIR /usr/src/codecrumbs
+
+COPY package*.json ./
+
+RUN yarn install
+
+COPY . .
+
+EXPOSE 2018 3018

README.md

@@ -1,48 +1,169 @@
-# codecrumbs [active development phase, stay tuned!] [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=Leave%20breadcrumbs%20in%20source%20code%20with%20codecrumbs%20tool%20&url=https://github.com/Bogdan-Lyashenko/codecrumbs&via=bliashenko&hashtags=javascript,code)
+ [![npm version](https://badge.fury.io/js/codecrumbs.svg)](https://badge.fury.io/js/codecrumbs) [![Open Source Love](https://badges.frapsoft.com/os/v2/open-source.svg?v=103)](https://github.com/ellerbrock/open-source-badges/) [<img src="https://img.shields.io/twitter/follow/bliashenko.svg?label=Stay%20Tuned&style=social">](https://twitter.com/bliashenko)
 
-[![npm version](https://badge.fury.io/js/codecrumbs.svg)](https://badge.fury.io/js/codecrumbs)
+<p align="center">
+    <img src="/docs/logo-sm.png" width="250"/>
+</p>
 
-Leave "breadcrumbs" in source code via comments to find your way out from code maze.
+<h3 align="center">
-> Still much work to do, but the basic features are already implemented and are ready to use. Give it a try while I am finishing a few more big features. Ideas and improvements are welcome. Thanks.
+  <a href="#what">What</a>
+  <span> · </span>
+  <a href="#demo">Demo</a>
+  <span> · </span>
+  <a href="#get-started">Get started</a>
+  <span> · </span>
+  <a href="#features">Features</a>
+  <span> · </span>
+  <a href="#case-studies">Case studies</a>
+  <span> · </span>
+  <a href="#support">Support</a>
+</h3>
 
-## [Demo](https://codecrumbs.io/)
+**Have you ever got lost in a big or unknown codebase?** This tool will help you to solve that. Also, it will increase your development speed and give more knowledge about your application architecture.
-Check out [**standalone version here**](https://codecrumbs.io/) with defined trail of codecrumbs.
+> If you like this project, follow me on Twitter [@bliashenko](https://twitter.com/bliashenko) to hear about things I am building. 
 
-[<img src="/docs/codecrumbs-ui.png" width="800">](https://codecrumbs.io/)
+## Codecrumbs v2
+Check out new version of this project as [standalone application](https://codecrumbs.io). Just in a few clicks you can start exploring a codebase in more efficient way, create interactive visual guides and share them with others on your own blog! See [quick guide here](https://codecrumbs.io/guides/web-app-with-github/).
+
+<p align="center">
+  <a href="https://codecrumbs.io" target="_blank">
+   <img src="https://codecrumbs.io/external/img/common/app-ui-1.png" />
+  </a>
+</p>
+
+
+## Demo
+Check out prepared example for [**standalone version running here**](https://codecrumbs.io/app).
+
+## Codecrumbs v1
+
+>**How it works?** You run `codecrumbs` command for a codebase, it analyzes source code and builds its visual representation. Write down a codecrumb-comment and codebase state will be reflected by visual client in browser on the fly.
+>
+> Check out [my talk at React-Finland](https://www.youtube.com/watch?v=S_1-1jzLxm4) for more details.
+
+
+<img src="/docs/main-ui-3.png" width="100%"/>
 
 ## Get started
-Install ```codecrumbs``` globally or in ```devDependencies```:
+### Install and run
-```yarn add codecrumbs -D```
+>Pre-condition: update/install `NodeJS` version to be >= *8.11.1*
 
-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.
+1) Install ```codecrumbs``` globally (```yarn global add codecrumbs```)
-```javascript
+2) Run ```codecrumbs -d project-src-dir -e project-src-dir/index.js```. Change parameters to match your project:```-d``` is *directory with source code*, ```-e``` is *entry point file* .
-  // package.json
+3) Go to [http://localhost:2018](http://localhost:2018/#) in the browser to check it out.
-  ...
-  "scripts": {
-    "start:cc": "codecrumbs -e src/index.js -d src"
-  }
 
-```
+### Configuration
+Run codecrumbs with CLI params or specify static config file `codecrumbs.config.js` (see example [here](/example-project/codecrumbs.config.js))
 
-Run ```yarn start:cc``` from the terminal. Go to [http://localhost:2018/#](http://localhost:2018/#) in the browser to check it out.
+CLI | Config file | Description | Example
+--- | --- | --- | ---
+```d``` | ```projectDir``` | Relative path to project source code directory | ```-d src```
+```e``` | ```entryPoint``` | Relative path to project source entry point file (must be inside ```dir```) | ```-e src/app.js```
+```x``` | ```excludeDir``` | Relative path(or paths separated by ```,```) to directories for exclusion | ```-x src/doc,src/thirdparty```
+```p``` | ```clientPort``` | Port for Codecrumbs client (optional, default *2018*) | ```-p 2019```
+```n``` | ```projectNameAlias``` | Project name alias (optional, default same as ```-d``` value) | ```-n my-hello-world```
+```C``` | - | Path to codecrumbs.config.js (optional, by default will try to find the file in PWD) | ```-C config/codecrumbs.config.js```
+```D``` | ```debugModeEnabled``` | Enable debug mode for logs (optional, default is ```false```) | ```-D```
 
-## Breadcrumbs
+## Features
-> Leave breadcrumbs by simply putting a comment in code, diagram wil be updated on the fly!
+### Breadcrumbs and trails
 
-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.
+<img src="/docs/cc-ui-3.png" width="750"/>
 
-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.).
+UI explained:
-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.
+- enable "Codecrumbs" switch to have codecrumbs tree on the scheme (drop-down contains extra configuration)
+- choose "current" codecrumbs trail to display (can be either trail or all other "simple" codecrumbs)
+- select connection between two steps (code for two codecrumbs will be opened in "Sidebar" under "Crumbs" tab)
+- set other options in dropdowns to configure behaviour of the diagram (show code blocks, details, etc.)
 
-<img src="/docs/live-changes.gif" width="800">
+**How to get there?**
 
-Check out [the introduction article here](https://itnext.io/how-to-navigate-the-maze-of-javascript-code-541250447cbb) for more details.
+Leave breadcrumb in code by writing down a comment: ```//cc:[parameters;]```.
 
+```cc``` (stands for "CodeCrumb") is a prefix which used by the parser; check example of parameters in the table below:
 
-## Learn and  share your knowledge
+Example | Description | Use case
-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!
+--- | --- | ---
-<img src="/docs/share-knowledge.gif" width="800">
+```//cc:remember place``` | simple breadcrumb, ```remember place``` is a title of our first breadcrumb | Mark an important place to not forget where it was
+```//cc:here is bug;well, seems like a bug in logic``` | simple breadcrumb, ```well, seems like a bug in logic``` is details for breadcrumb, separated by ```;``` | Add extra information, will be rendered in popups
+```//cc:signin#3;enable route``` | trail of breadcrumbs,```signin``` is the **trail ID**, ```#3``` is order **number of step**, ```enable route``` is a title describing the step. | A sequence of codecrumbs, use to describe some data flow (e.g. user login, or form submit, etc.).
+```//cc:signin#1;firebase sign in;+2;do call to firebase with credentials``` | trail of breadcrumbs,```+2``` is number of lines to highlight, separated by ```;``` | Use number of lines to highlight the code related to breadcrumb
+
+> Note: current version supports single line comments only.
+
+> Hint: you can use trail id without step number (e.g. ```//cc:groupname#;test```) just to group breadcrumbs, you always can add step numbers later when you know the correct order. 
+
+### 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. To control a diagram UI - select it by clicking on it.
+
+E.g. for client-server 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 (**no** need to have them like mono-repo, etc.), simply run `codecrumbs` for directory you need.
+
+<img src="/docs/multi-codebase-cc-2.png" width="100%"/>
+
+### Multi-language support
+Current version supports next programming languages:
+- `C#`
+- `C++`
+- `Fortran`
+- `Go`
+- `Haskell`
+- `Java`
+- `JavaScript`
+- `Kotlin`
+- `PHP`
+- `Python`
+- `Ruby`
+- `TypeScript`
+
+Please file an issue to support other language you would like to have.
+
+### Dependencies
+> Note: In current version only [JavaScript, TypeScript] offer this feature
+
+<img src="/docs/dep-ui-2.png" width="100%"/>
+
+UI explained:
+
+- enable "Dependencies" switch
+- select connection between modules (all involved files will be opened in "Sidebar", so you can see “what is imported” and “its implementation”)
+
+### Flowchart
+> Note: In current version only JavaScript offers this feature
+
+<img src="/docs/flow-ui.png" width="100%"/>
+
+[js2flowchart](https://github.com/Bogdan-Lyashenko/js-code-to-svg-flowchart) is used in the sidebar to draw flowchart for the selected file code.
 
 ## Support
+Any support is very much appreciated! 👍 😘 ❤️
+If you like this project, please, **put a :star: and tweet about it**. Thanks!
 
-If you like this project and believe it makes sense, please, put a :star: or tweet about it - it will show your support and motivate me :punch:. Thanks! 
+Please, consider [making financial donation](https://opencollective.com/codecrumbs), it will help further development of more cool features! We'll thank you by including your name/company logo here ☺️. Feel free to [ping me](https://www.linkedin.com/in/bohdan-liashenko-bb365854/) for discussion.
+
+<a href="https://opencollective.com/codecrumbs/donate" target="_blank">
+  <img src="https://opencollective.com/codecrumbs/donate/button@2x.png?color=blue" width=300 />
+</a>
+
+#### Sponsors
+Development supported by [0+X](https://0x.se)
+
+<a href="https://0x.se" target="_blank">
+  <img src="https://avatars0.githubusercontent.com/u/16350669?s=200&v=4" width=100 />
+</a>
+
+#### Backers
+<a href="https://opencollective.com/codecrumbs/backer/0/website" target="_blank"><img src="https://opencollective.com/codecrumbs/backer/0/avatar.svg"></a>
+<a href="https://opencollective.com/codecrumbs/backer/1/website" target="_blank"><img src="https://opencollective.com/codecrumbs/backer/1/avatar.svg"></a>
+<a href="https://opencollective.com/codecrumbs/sponsor/0/website" target="_blank"><img src="https://opencollective.com/codecrumbs/sponsor/0/avatar.svg"></a>
+
+## 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](https://github.com/Bogdan-Lyashenko/) of this repository before making a change. Ideas and suggestions are welcome.
+To start development environment, clone the repo & run:
+```javascript
+yarn && yarn start
+```
+
+## WIP
+Next features are developing:
+- **VS Code extension** - some neat features right inside the code editor. Checkout [the repo here](https://github.com/Bogdan-Lyashenko/vs-code-codecrumbs).

cli/index.cli.js

@@ -1,36 +1,57 @@
 #!/usr/bin/env node
 
+const path = require('path');
 const program = require('commander');
 const colors = require('colors');
+const _ = require('lodash');
 
+const showUpdatesInfo = require('./updatesInfo');
 const server = require('../src/server');
 
+showUpdatesInfo();
+
 program
-  .option('-e, --entry [entryFile]', 'Specify path to entry point file. E.g. `./src/app.js`')
+  .option('-e, --entry [entryPoint]', 'Specify path to entry point file. E.g. `src/app.js`')
-  .option('-d, --dir [projectDir]', 'Specify path to project source code directory. E.g. `./src`')
+  .option('-d, --dir [projectDir]', 'Specify path to project source code directory. E.g. `src`', '')
   .option(
     '-w, --webpack [webpackConfigFile]',
-    'Specify path to webpack config file. E.g. ./webpack.config.js'
+    'Specify path to webpack config file. E.g. webpack.config.js'
+  )
+  .option(
+    '-t, --tsconfig [tsConfigFile]',
+    'Specify path to typeScript config file. E.g. tsConfig.json'
   )
   .option('-p, --port [defaultPort]', 'Specify port for Codecrumbs client. E.g. 3333', 2018)
+  .option('-i, --ideCmd [ideCmd]', 'IDE command to open file')
+  .option('-x, --excludeDir [excludeDirectories]', 'Exclude directories')
+  .option('-n, --projectName [projectNameAlias]', 'Project name alias')
+  .option('-C, --configFile [pathToConfigFile]', 'Path to codecrumbs.config.js')
+  .option('-D, --debugModeEnabled [debugModeEnabled]', 'Enable debug mode for logs.')
   .parse(process.argv);
 
-if (!program.entry && !program.dir) {
+const pathToConfigFile = program.configFile || 'codecrumbs.config.js';
+const configFileExists = server.checkIfPathExists(pathToConfigFile);
+if ((!program.entry || !program.dir) && !configFileExists) {
   console.log(
     colors.magenta(
-      'Please specify `entry` and `dir` params. E.g. `codecrumbs -e src/app.js -d src`'
+      'Please specify `entryPoint` and `projectDir` params (e.g. `codecrumbs -e src/app.js -d src`). Or use `-C codecrumbs.config.js` instead.'
     )
   );
   process.exit();
 }
 
-server.setup(
+const configFromFile = configFileExists ? require(path.resolve(pathToConfigFile)) : {};
-  {
+
-    projectNameAlias: undefined, // TODO: add param for this
+const configFromCLI = {
-    entryPoint: program.entry,
+  projectNameAlias: program.projectName,
-    projectDir: program.dir,
+  entryPoint: program.entry,
-    webpackConfigPath: program.webpack,
+  projectDir: program.dir,
-    clientPort: program.port
+  webpackConfigPath: program.webpack,
-  },
+  tsConfigPath: program.tsconfig,
-  false
+  clientPort: program.port,
-);
+  excludeDir: program.excludeDir,
+  ideCmd: program.ideCmd,
+  debugModeEnabled: program.debugModeEnabled
+};
+
+server.setup(_.merge(configFromCLI, configFromFile), { isDev: false });

cli/updatesInfo.js

@@ -0,0 +1,20 @@
+const colors = require('colors');
+const exec = require('child_process').exec;
+
+module.exports = () => {
+  try {
+    exec('npm outdated codecrumbs').stdout.on('data', function(data) {
+      const list = data
+        .split('  ')
+        .filter(v => !!v)
+        .map(v => v.trim());
+
+      const latestVersion = list[list.length - 2];
+      console.log(
+        colors.cyan.underline(
+          `There is new version of codecrumbs (${latestVersion}) available! Please update to have all latest features and improvements!`
+        )
+      );
+    });
+  } catch (e) {}
+};

example-project/codecrumbs.config.js

@@ -0,0 +1,7 @@
+module.exports = {
+  entryPoint: 'example-project/src-client/index.js',
+  projectDir: 'example-project/src-client',
+  clientPort: 1234,
+  projectNameAlias: 'example-project-for-client',
+  debugModeEnabled: true
+};

example-project/debug/index.js

@@ -0,0 +1 @@
+//cc:debug#0;step 0

example-project/debug/sections/one.js

@@ -0,0 +1 @@
+//cc:debug#2;step 2

example-project/debug/sections/two.js

@@ -0,0 +1,3 @@
+//cc:debug#4;step 4
+
+//cc:debug#1;step 1

example-project/debug/utils/changeListener/behaviour.js

@@ -0,0 +1 @@
+//cc:debug#3;step 3

example-project/languages/cpp-lang.cpp

@@ -0,0 +1,9 @@
+#include <iostream>
+using namespace std;
+
+//cc:main function
+int main()
+{
+    cout << "Hello, World!";
+    return 0;
+}

example-project/languages/csharp-lang.cs

@@ -0,0 +1,16 @@
+//cc:main function
+using System;
+namespace HelloWorld
+{
+    class Hello
+    {
+        static void Main()
+        {
+            Console.WriteLine("Hello World!");
+
+            // Keep the console window open in debug mode.
+            Console.WriteLine("Press any key to exit.");
+            Console.ReadKey();
+        }
+    }
+}

example-project/languages/fortran-lang.f

@@ -0,0 +1,4 @@
+! cc: main function
+program hello
+  print *, "Hello World!"
+end program hello

example-project/languages/go-lang.go

@@ -0,0 +1,7 @@
+package main
+import "fmt"
+
+// cc:main function
+func main() {
+    fmt.Println("hello world")
+}

example-project/languages/haskell-lang.hs

@@ -0,0 +1,2 @@
+-- cc:main function
+putStrLn "Hello, world!"

example-project/languages/java-lang.java

@@ -0,0 +1,9 @@
+public class HelloWorld {
+
+    //cc: main function
+    public static void main(String[] args) {
+        // Prints "Hello, World" to the terminal window.
+        System.out.println("Hello, World");
+    }
+
+}

example-project/languages/js-lang.js

@@ -0,0 +1,4 @@
+//cc:main function
+function greeting() {
+  console.log('Hello world!');
+}

example-project/languages/kotlin-lang.kt

@@ -0,0 +1,5 @@
+//cc:main function
+
+fun main(args : Array<String>) {
+    println("Hello, World!")
+}

example-project/languages/lua-lang.lua

@@ -0,0 +1,2 @@
+-- hello world program
+print ("Hello World!")

example-project/languages/ocaml.ml

@@ -0,0 +1,2 @@
+/* cc:main function */
+let hello = () => "Hello, World!";

example-project/languages/perl-lang.pl

@@ -0,0 +1,7 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+
+# cc: main function.
+print "Hello, World!\n";

example-project/languages/php-lang.php

@@ -0,0 +1,5 @@
+<?php
+  //cc:main function
+  echo "Hello World!";
+  echo "PHP is so easy!";
+?>

example-project/languages/python-lang.py

@@ -0,0 +1,10 @@
+import sys
+
+# cc:main function
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv
+
+    print "Hello, world"
+
+    return

example-project/languages/ruby-lang.rb

@@ -0,0 +1,3 @@
+# cc:main function
+
+puts 'Hello, world!'

example-project/languages/ts-lang.ts

@@ -0,0 +1,4 @@
+//cc:main function
+function greeting() {
+  console.log('Hello world!');
+}

example-project/src-client/auth/actions.js

@@ -10,7 +10,7 @@ import {
 
 function authenticate(provider) {
   return dispatch => {
-    //cc:signin#1;firebase sign in;+2
+    //cc:signin#1;firebase sign in;+1;call to firebase with auth provider, proceed if success response
     firebaseAuth.signInWithPopup(provider)
       .then(result => dispatch(signInSuccess(result)))
       .catch(error => dispatch(signInError(error)));

example-project/src-client/auth/reducer.js

@@ -13,7 +13,7 @@ export function authReducer(state = new AuthState(), {payload, type}) {
     case INIT_AUTH:
     case SIGN_IN_SUCCESS:
       return state.merge({
-        authenticated: !!payload, // cc:signin#2;toggle 'authenticated' flag
+        authenticated: !!payload, //cc:signin#5;toggle 'authenticated' flag
         id: payload ? payload.uid : null
       });
 

example-project/src-client/firebase/config.js

@@ -1,3 +1,4 @@
+//cc:firebase config;and some details
 export const firebaseConfig = {
   apiKey: 'AIzaSyBsVVpEDrlNPEmshLcmOuE0FxhjPn0AqMg',
   authDomain: 'todo-react-redux.firebaseapp.com',

example-project/src-client/index.js

@@ -15,7 +15,7 @@ import App from './views/app';
 const store = configureStore();
 const rootElement = document.getElementById('root');
 
-//cc:layout#0;start;provider
+//cc:layout#0;start
 function render(Component) {
   ReactDOM.render(
     <Provider store={store}>

example-project/src-client/test_tml.vue

@@ -0,0 +1,22 @@
+
+<template>
+    <p>{{ greeting }} World!</p>
+</template>
+
+<script>
+  module.exports = {
+    data: function () {
+      return {
+        greeting: 'Hello'
+      }
+    }
+  }
+</script>
+
+//cc:test vue
+<style scoped>
+    p {
+        font-size: 2em;
+        text-align: center;
+    }
+</style>

example-project/src-client/views/app/app.js

@@ -10,7 +10,7 @@ import RequireUnauthRoute from '../components/require-unauth-route';
 import SignInPage from '../pages/sign-in';
 import TasksPage from '../pages/tasks';
 
-//cc:layout#1;describe pages
+//cc:layout#1;describe pages;some details long description for separare popup
 const App = ({authenticated, signOut}) => (
   <div>
     <Header

example-project/src-client/views/components/require-auth-route/require-auth-route.js

@@ -1,7 +1,7 @@
 import React from 'react';
 import { Route, Redirect } from 'react-router-dom'
 
-//cc:signin#3;enable route;+6
+//cc:signin#6;enable route;details
 const RequireAuthRoute = ({component: Component, authenticated, ...rest}) => (
   <Route
     {...rest}

example-project/src-client/views/components/task-item/task-item.js

@@ -6,7 +6,7 @@ import Icon from '../icon';
 
 import './task-item.css';
 
-//cc:there is task
+//cc:there is task;extra
 export class TaskItem extends Component {
   constructor() {
     super(...arguments);