Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
137 lines (87 loc) · 4.87 KB

GETTING_STARTED.md

File metadata and controls

137 lines (87 loc) · 4.87 KB

Code Graph Analysis Pipeline - Getting started guide

This document describes the steps to get started as quickly as possible.
👉 For more details on what else you can do see README.
👉 For more details on how the commands work in detail see COMMANDS.

🛠 Prerequisites

Please read through the Prerequisites in the README file for what is required to run the scripts or simply run the checkCompatibility.sh script to verify that your environment is set up correctly.

The easiest way to get started

Just run one of the following examples in the directory of this file:

Use these optional command line options as needed:

  • (Recommended) Only create CSV reports and skip Python and Node.js dependent reports. Example:

    ./scripts/examples/analyzeAxonFramework.sh --report CSV

  • Only explore the graph manually in the browser (http://localhost:7474/browser). Skip all automated reports. Example:

    ./scripts/examples/analyzeAxonFramework.sh --explore

  • Add the version number of the project to pick a specific one. Example:

    ./scripts/examples/analyzeAxonFramework.sh 4.10.1

Start an own analysis

1. Setup

  • Choose an initial password for Neo4j if not already done.

    export NEO4J_INITIAL_PASSWORD=theinitialpasswordthatihavechosenforneo4j

  • Initialize you analysis project using ./init.sh.

    ./init.sh MyAnalysisProjectName

  • Change into the analysis directory.

    cd ./temp/MyAnalysisProjectName

2. Prepare the code to be analyzed

  • Move the artifacts (e.g. Java jars json files) you want to analyze into the artifacts directory.

  • If you want to analyze Typescript code, create a symbolic link inside the source directory that points to the Typescript project. Alternatively you can also copy the project into the source directory.

  • If you want to include git data like changed files and authors, create a symbolic link inside the source directory that points to the repository or clone it into the source directory. If you already have your Typescript project in there, you of course don't have to do it twice. If you are analyzing Java artifacts (full source not needed), it is sufficient to use a bare clone that only contains the git history without the sources using git clone --bare. If you want to focus on one branch, use --branch branch-name to checkout the branch and --single-branch to only fetch the history of that branch.

  • Alternatively to the steps above, run an already predefined download script

    ./../../scripts/downloader/downloadAxonFramework.sh <version>

  • Optionally use a script to download artifacts from Maven (details).

Start the analysis

  • Without any additional dependencies:

    ./../../scripts/analysis/analyze.sh --report Csv

  • Jupyter notebook reports when Python and Conda (or venv) are installed (and Chromium Browser for PDF generation):

    ./../../scripts/analysis/analyze.sh --report Jupyter

  • Python reports when Python and Conda (or venv) are installed (without Chromium Browser for PDF generation):

    ./../../scripts/analysis/analyze.sh --report Python

  • Graph visualizations with GraphViz installed or npx to run it indirectly:

    ./../../scripts/analysis/analyze.sh --report Visualization

  • Markdown reports:

    ./../../scripts/analysis/analyze.sh --report Markdown

  • All reports with Python, Conda (or venv), Node.js and npm installed:

    ./../../scripts/analysis/analyze.sh

  • To explore the database yourself without any automatically generated reports and no additional requirements:

    ./../../scripts/analysis/analyze.sh --explore

  • Only run the reports of one specific domain (vertical slice):

    ./../../scripts/analysis/analyze.sh --domain anomaly-detection

  • Only run the CSV reports of one specific domain:

    ./../../scripts/analysis/analyze.sh --domain anomaly-detection --report Csv

👉 Open your browser and login to your local Neo4j Web UI (http://localhost:7474/browser) with "neo4j" as user and the initial password you've chosen.

GitHub Actions

👉 See Code Structure Analysis Pipeline on how to do this within a GitHub Actions Workflow.