+
+
+
+
+
+
-
+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.
+
+
+
+
## Get started
### Install and run
->Pre-condition: update/install `NodeJS` version to be >= *8.11.1*
-
+>Pre-condition: update/install `NodeJS` version to be >= *8.11.1*
+
1) Install ```codecrumbs``` globally (```yarn global add codecrumbs```)
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* .
3) Go to [http://localhost:2018](http://localhost:2018/#) in the browser to check it out.
-### CLI
-Parameter | Description | Example
---- | --- | ---
-```-d```, ```--dir``` | Path to project source code directory | ```-d src```
-```-e```, ```--entry``` | Path to project source entry point file (must be inside ```dir```) | ```-e src/app.js```
-```-p```, ```--port``` | Port for Codecrumbs client (optional, default *2018*) | ```-p 2019```
-```-n```, ```--projectName``` | Project name alias (optional, default same as ```-d``` value) | ```-n my-hello-world```
+### Configuration
+Run codecrumbs with CLI params or specify static config file `codecrumbs.config.js` (see example [here](/example-project/codecrumbs.config.js))
+
+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```
## Features
### Breadcrumbs and trails
-
+
UI explained:
-1) Enable "Codecrumbs" to have codecrumbs tree on the scheme (drop-down contains extra configuration)
-2) Choose "current" codecrumbs flow to display (can be either trail or all other "simple" codecrumbs)
-3) Codecrumb details
-4) Folder is in "active only" state, you can expand to show all children
+- 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.)
+
+**How to get there?**
+
+Leave breadcrumb in code by writing down a comment: ```//cc:[parameters;]```.
-**How to get there?** 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:
-```cc``` (stands for "CodeCrumb") is a prefix which used by the parser; check example of parameters in the table below:
-
Example | Description | Use case
--- | --- | ---
```//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
+```//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.
+> 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.
+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.
-
+
### Multi-language support
-Current version supports next programming languages:
+Current version supports next programming languages:
+- `C#`
+- `C++`
+- `Fortran`
+- `Go`
+- `Haskell`
+- `Java`
- `JavaScript`
-- `TypeScript`
+- `Kotlin`
+- `PHP`
- `Python`
- `Ruby`
-- `PHP`
-- `Java`
-- `Kotlin`
-- `C++`
-- `C#`
-- `Fortran`
+- `TypeScript`
Please file an issue to support other language you would like to have.
-### Download & Upload (learn and share your knowledge)
-
-You can take a snapshot of application state at any point of time and share it with others. Simply download the json file of codecrumbs store (*top-right corner, "setup -> download"*). This json file can be then uploaded to codecrumbs (*top-right corner, "setup -> upload"*) to represent exactly same picture, even without having that project locally!
-
-
-
### Dependencies
-> Note: In current version only JavaScript offers this feature
+> Note: In current version only [JavaScript, TypeScript] offer this feature
-
+
UI explained:
-1) Enable "Dependencies"
-2) Select connection between modules
-3) All involved files (two or more) will be opened in "Sidebar", so you can see “what is imported” and “its implementation”.
+- 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
+> Note: In current version only JavaScript offers this feature
[js2flowchart](https://github.com/Bogdan-Lyashenko/js-code-to-svg-flowchart) is used in the sidebar to draw flowchart for the selected file code.
-## Case studies
-The tool (codecrumbs) allows us to learn, document and explain a codebase much faster. Also, with *Download & Upload* feature it becomes super easy to collect and share your "investigation results".
-
-The ultimate goal is to have many case studies hosting at [https://codecrumbs.io](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! 👍 😘 ❤️
If you like this project, please, **put a :star: and tweet about it**. Thanks!
@@ -131,11 +143,19 @@ Please, consider [making financial donation](https://opencollective.com/codecrum
-
+
+
+#### Sponsors
+Development supported by [0+X](https://0x.se)
+
+
+ 
+
#### Backers
+
## 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.
@@ -146,6 +166,4 @@ yarn && yarn start
## WIP
Next features are developing:
-- **eject codecrumbs** - ability to remove all "breadcrumbs" from source code in "one click"
-- **data transferring between cc trail steps**
-- **VS Code extension** - some neat features right inside the code editor. Checkout [the repo here](https://github.com/Bogdan-Lyashenko/vs-code-codecrumbs).
+- **VS Code extension** - some neat features right inside the code editor. Checkout [the repo here](https://github.com/Bogdan-Lyashenko/vs-code-codecrumbs).
diff --git a/cli/index.cli.js b/cli/index.cli.js
old mode 100644
new mode 100755
index 7111f6a7..95f1c466
--- a/cli/index.cli.js
+++ b/cli/index.cli.js
@@ -1,43 +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(
- '-d, --dir [projectDir]',
- 'Specify path to project source code directory. E.g. `src`',
- ''
- )
+ .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(
'-w, --webpack [webpackConfigFile]',
'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('-f, --parserFallback [astParserFallback]', 'Use AST parser fallback')
+ .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(
- {
- projectNameAlias: program.projectName,
- entryPoint: program.entry,
- projectDir: program.dir,
- webpackConfigPath: program.webpack,
- clientPort: program.port,
- astParserFallback: program.parserFallback
- },
- false
-);
+const configFromFile = configFileExists ? require(path.resolve(pathToConfigFile)) : {};
+
+const configFromCLI = {
+ projectNameAlias: program.projectName,
+ entryPoint: program.entry,
+ projectDir: program.dir,
+ webpackConfigPath: program.webpack,
+ tsConfigPath: program.tsconfig,
+ clientPort: program.port,
+ excludeDir: program.excludeDir,
+ ideCmd: program.ideCmd,
+ debugModeEnabled: program.debugModeEnabled
+};
+
+server.setup(_.merge(configFromCLI, configFromFile), { isDev: false });
diff --git a/cli/updatesInfo.js b/cli/updatesInfo.js
new file mode 100644
index 00000000..915b371d
--- /dev/null
+++ b/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) {}
+};
diff --git a/docs/cc-ui-3.png b/docs/cc-ui-3.png
new file mode 100644
index 00000000..d47bc080
Binary files /dev/null and b/docs/cc-ui-3.png differ
diff --git a/docs/cc-ui.png b/docs/cc-ui.png
deleted file mode 100644
index 13d565ed..00000000
Binary files a/docs/cc-ui.png and /dev/null differ
diff --git a/docs/dep-ui-2.png b/docs/dep-ui-2.png
new file mode 100644
index 00000000..ac715734
Binary files /dev/null and b/docs/dep-ui-2.png differ
diff --git a/docs/dep-ui.png b/docs/dep-ui.png
deleted file mode 100644
index 3e0f95a6..00000000
Binary files a/docs/dep-ui.png and /dev/null differ
diff --git a/docs/ide-integration.gif b/docs/ide-integration.gif
new file mode 100644
index 00000000..0009257f
Binary files /dev/null and b/docs/ide-integration.gif differ
diff --git a/docs/main-ui-3.png b/docs/main-ui-3.png
new file mode 100644
index 00000000..4e633632
Binary files /dev/null and b/docs/main-ui-3.png differ
diff --git a/docs/main-ui.png b/docs/main-ui.png
deleted file mode 100644
index 03c4d9bb..00000000
Binary files a/docs/main-ui.png and /dev/null differ
diff --git a/docs/multi-codebase-cc-2.png b/docs/multi-codebase-cc-2.png
new file mode 100644
index 00000000..c669869b
Binary files /dev/null and b/docs/multi-codebase-cc-2.png differ
diff --git a/docs/multi-l-c.png b/docs/multi-l-c.png
deleted file mode 100644
index a8d586a6..00000000
Binary files a/docs/multi-l-c.png and /dev/null differ
diff --git a/docs/upload-feature-2.gif b/docs/upload-feature-2.gif
deleted file mode 100644
index 6f910208..00000000
Binary files a/docs/upload-feature-2.gif and /dev/null differ
diff --git a/example-project/codecrumbs.config.js b/example-project/codecrumbs.config.js
new file mode 100644
index 00000000..c940c70c
--- /dev/null
+++ b/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
+};
diff --git a/example-project/debug/index.js b/example-project/debug/index.js
new file mode 100644
index 00000000..e1214cc1
--- /dev/null
+++ b/example-project/debug/index.js
@@ -0,0 +1 @@
+//cc:debug#0;step 0
\ No newline at end of file
diff --git a/example-project/debug/sections/one.js b/example-project/debug/sections/one.js
new file mode 100644
index 00000000..bac217c6
--- /dev/null
+++ b/example-project/debug/sections/one.js
@@ -0,0 +1 @@
+//cc:debug#2;step 2
\ No newline at end of file
diff --git a/example-project/debug/sections/two.js b/example-project/debug/sections/two.js
new file mode 100644
index 00000000..f4978353
--- /dev/null
+++ b/example-project/debug/sections/two.js
@@ -0,0 +1,3 @@
+//cc:debug#4;step 4
+
+//cc:debug#1;step 1
\ No newline at end of file
diff --git a/example-project/debug/utils/changeListener/behaviour.js b/example-project/debug/utils/changeListener/behaviour.js
new file mode 100644
index 00000000..872d1823
--- /dev/null
+++ b/example-project/debug/utils/changeListener/behaviour.js
@@ -0,0 +1 @@
+//cc:debug#3;step 3
diff --git a/example-project/debug/x1/index.js b/example-project/debug/x1/index.js
new file mode 100644
index 00000000..e69de29b
diff --git a/example-project/debug/x2/ok/ok.js b/example-project/debug/x2/ok/ok.js
new file mode 100644
index 00000000..e69de29b
diff --git a/example-project/debug/x2/x/index.js b/example-project/debug/x2/x/index.js
new file mode 100644
index 00000000..e69de29b
diff --git a/example-project/languages/cpp-lang.cpp b/example-project/languages/cpp-lang.cpp
index 83bf30a8..e0d2bc77 100644
--- a/example-project/languages/cpp-lang.cpp
+++ b/example-project/languages/cpp-lang.cpp
@@ -1,7 +1,7 @@
#include {{ greeting }} World!
+ + + + +//cc:test vue + \ No newline at end of file diff --git a/example-project/src-client/views/app/app.js b/example-project/src-client/views/app/app.js index cf89ec0d..d6e05e1c 100644 --- a/example-project/src-client/views/app/app.js +++ b/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}) => (