README.md

CodeCharta Visualization

CodeCharta by MaibornWolff

Jump to Section

• Installation
• Development Tasks
• Testing
• JSON structure
• License

Installation

You can start with Codecharta Visualization on multiple ways:

• Installation as a npm package (Recommended for users)
• Run an operating system specific standalone
• Build it yourself from the github repository (Development)
• Use docker-compose to run this with other needed tools like a Sonar instance or analyzing tools of codecharta-analysis.
• Use our Dockerfile to run the visualization in a container
• Try out the online version

Be aware, that if you are on Apple Silicon, you may run into problems with the standalone and build versions

NPM Package

Make sure you have Node.js (version >=20) installed
For reference: Codecharta-Visualization on NPM

# Install the package globally via npm
$ npm i -g codecharta-visualization
# Run it anywhere (you might need administrative rights/sudo)
# You might need to restart your terminal
$ codecharta-visualization

Run a standalone

• Download the correct standalone version for your OS from the latest release page under 'Assets'
• Extract & run the application

MacOS

If you get an error on MacOS because of a missing license, try this apple support article
You may be required to give the application executable rights

If you are using an M1 or similar (arm64) architectures you might need to do additional steps, because the OS might flag the executable as damaged, if it is downloaded and from an unverified developer:

• Remove the 'downloaded' attributes from the OS: $ xattr -cr codecharta-visualization.app/

Build it yourself

To clone and run this application, you'll need Git and Node.js (version >=20) installed

(Windows) For some tasks the Git bash utilities are required

# Clone the CodeCharta repo
$ git clone https://github.com/MaibornWolff/codecharta.git
# Navigate to Visualization
$ cd codecharta/visualization
# Installation.
$ npm install
# Run the development server
$ npm run dev
# Upload any .cc.json!

Tasks

After cloning the repository and running the npm installation as described above, you can use the other available commands and tasks inside the visualization project. You can check all tasks and their functionality inside the package.json section scripts.

Build

Build the project in dist/webpack. The produced files are required if you want to package the application or start the standalone version.

Additional files are copied inside the webpack, which are required to execute the electron standalone via npm (run) start. Note that the build command requires unix tools on path, so on Windows add them to it or use the bash shell

# Make sure you are still inside the visualization project
$ cd visualization
# Build the webpack without serving it
$ npm run build
# The webpack is inside the dist/webpack/ folder, which you can serve as a web application

Package

Package the electron application to produce the standalone versions for Windows, Linux and MacOS for distribution and testing. The different versions are inside the dist/applications folder.

Make sure to run the build task beforehand
This process might require administrative rights/sudo depending on the OS
For UNIX-based systems you probably need to install Wine to package the Windows application
The MacOS version usually can't be packaged while using Windows

$ npm run package
# If you only want to produce the standalone version for your current OS/arch combo use package:local
$ npm run package:local

For each application there will be a .zip file inside the dist/packages folder. Zipping is part of the npm run package process. You can check the scripts inside script/app*.js for details.

Dev

# Build the webpack and serve it under localhost:3000
$ npm run dev
# This server listens to file changes

Start

Make sure to run build beforehand

# Start the electron application
$ npm run start

---

Testing

To run tests check out the following tasks:

Unit

Run unit tests in app/ and generate a coverage report in dist/coverage/.

# Executes test with reduced CPU usage to avoid memory problems
$ npm run test
# To run the tests in watch mode, use
$ npm run test:auto
# To run as many tests in parallel as possible
$ npm run test:ci

E2E

Run end-to-end tests

# Make sure to stop the dev-webserver before continuing
# Create an up-to-date build
$ npm run build
# Start the e2e tests
$ npm run e2e
# To run the tests in watch mode, use
$ npm run e2e:auto

To follow/watch the steps the e2e test is performing, deactivate headless mode in jest-puppeteer.config.js (and maybe set the slowMo parameter)

Run in Docker container

You can use this via docker compose or as a standalone container. This section will deal with how to use the visualization as a standalone container. For information on how to use this with docker compose, please check out Docker Getting Started We assume that you already installed docker, if not, you have to do that before!

To containerize the visualization, please follow the below listed steps.

• Start the docker container: docker run -d -p 9000:80 codecharta/codecharta-visualization. This detaches the container and exposes port 80 on the container and port 9000 on the host.
• Open localhost:9000 in your browser and you can already use the visualization, upload cc.json files and play around!

Code Style

Please check out the DEV_START_GUIDE.