Analysis
The Analysis, also known as CodeCharta Shell (ccsh), is a command-line interface (CLI) tool, which is used to generate cc.json files that can be used by the visualization. It is a convenient way to access various tools to generate metrics, import metrics from other sources or adjust existing cc.json files. These tools in turn are divided into parsers, importers, filters and exporters.
- Parser: Generate metrics from a given source (e.g. source code or log files) and return a
cc.jsonfile - Importer: Converts the output generated by an external source (e.g. SonarQube) to
cc.jsonformat - Filter: Modifies a (or multiple) given
cc.jsonand returns anothercc.json - Exporter: Takes a
cc.jsonfile and exports it to other formats
For further documentation considering the tools used in CodeCharta, please check out the CodeCharta Shell page.
Metrics
The metric that are generated vary significantly based on the tool used. Some tools focus on metrics for specific code files (e.g. number of code lines, complexity, etc.) while other focus on metadata of files (e.g. number of authors, number of commits, etc.). Some tools also generate so called ‘edge metrics’, which link different files together (e.g. pairing rate, which means that when one file is committed, another is frequently in the same commit).
The cc.json format
The output of all ccsh tools (except exporters) is a cc.json file. This format is a json file that indicates it can be loaded into the CodeCharta visualization to visualize metrics of the analyzed code. It mainly consists of a list of nodes, where each node can be a folder or a file. Files contain a list of attributes, which are the different metrics for that file. Folders contain a list of children which in themselves can be folders or files. This represents the natural folder structure of the code. If the cc.json file contains edge metrics they are sorted in a list, similar to the nodes. However, this list is not required for a valid cc.json as edge metrics are an optional feature that is only supported by some ccsh tools.
For additional properties check out the cc.json schema changelog.
Available tools
This is a list of all tools available in the ccsh. Each of these tools has its own page with further documentation which can be reached by clicking on the tools name.
| Name | Category | Description |
|---|---|---|
| SourceCodeParser | Parser | Generates metrics from given source code (currently only supports Java code) |
| RawTextParser | Parser | Can generate metrics from any language as it only considers the raw text |
| GitLogParser | Parser | Generated metrics based on a given git-log file or git repo (this generates the git-log on the fly) |
| SVNLogParser | Parser | Generates metrics based on a given SVN-log file |
| SonarImporter | Importer | Imports metrics generated by SonarQube |
| TokeiImporter | Importer | Imports metrics generated by Tokei |
| CSVImporter | Importer | Turns generic CSV files of the right format to cc.json |
| SourceMonitorImporter | Importer | Imports metrics generated by SourceMonitor |
| CodeMaatImporter | Importer | Imports metrics generated by CodeMaat |
| MetricGardenerImporter | Importer | Imports metrics generated by MetricGardener (can also directly execute it on the fly) |
| CSVExporter | Exporter | Exports a cc.json file as CSV |
| EdgeFilter | Filter | Turns cc.json files that only contain edge data into normal, visualizable cc.json files |
| MergeFilter | Filter | Merges multiple cc.json files into one |
| StructureModifier | Filter | Allows to modify the structure of a cc.json file without manually changing it |
Goal
The goal of the CodeCharta analysis is to be as flexible as possible when combining metrics.
There are many tools already available that generate metrics and we wanted to incorporate them as much as possible because we are standing on the shoulder of giants. Since most of them provide some kind of metrics export in a common format (csv, json, …) we naturally started out writing many small importers per source. For example, we wrote a Sonarimporter, then a Csvimporter and later a Mergefilter to combine these sources. After a while this became a bit unwieldy and we bundled all these small tools under the banner of the CodeCharta Shell (ccsh).
All of these tools have in common that their input and/or output is a .cc.json which they usually enrich with quantitative measurements called metrics. We think these metrics are in some ways flawed but still very useful as a conversation starter. However, they should never finish a conversation (“You have to increase line_coverage!”).
If you want to learn more, you can read about good and bad metrics, how the ccsh works or how to create custom metrics or importers. And if you want to learn more about the CodeCharta importer and parser, have a look on the Analysing tools section.