The CodeCharta Shell (ccsh) is a convenient way to access the various tools. They in turn are divided into importers, filters and exporters.

  • Importers take a source like Sonar and return a .cc.json
  • Filters take a .cc.json and return a .cc.json
  • Exporters take a .cc.json and return the target format

If you want to combine multiple metrics into one .cc.json you should get comfortable with the merge mapper. Some importers support direct pipe-through, which means you don’t have to use the merge mapper. If these importers are missing a metric, please take a look at Custom Metrics and Importer.

For further documentation considering the tools used in CodeCharta, please read the analysing-tools section.

Parser Suggestions

When launching CodeCharta Shell without any arguments and options, CodeCharta automatically tries to suggest useful parsers to the user. To do this, a resource has to be entered which can be a path to a file or folder or an url. CodeCharta then automatically checks all parsers which support this feature and offers the user to select from a list of all parsers which have been identified as applicable.

After choosing the parsers, a dry run to configure each parser is started using the Interactive Shell. When all parsers are configured, the user can either manually run the parsers by executing the command output by the Interactive Shell or run them together automatically. If the latter option is selected, all configured parsers are run in parallel.

If every parser is run successfully, the shell offers the user to merge the result files. To do that, each parsers result cc.json has to be moved into the same folder.

Currently, the following parsers are considered when checking for recommendations:

  • GitLogParser
  • SVNLogParser
  • SonarImporter
  • MetricGardenerImporter
  • SourceCodeParser
  • RawTextParser

Interactive Shell

The interactive shell aims to aid users when executing parsers by collecting all needed options and arguments for the corresponding parser. You can launch the interactive shell by calling ccsh -i or ccsh --interactive. There you are asked which parser you want to run and receive questions helping you configure that parser.

Alternatively, you can directly run the interactive dialog for a parser by calling it without arguments, e.g. ccsh sonarimport.

In the end, the full command to launch the parser in the configured way is output for future use.

Filters

Edge Filter

Generates visualisation data from a cc.json file with edges data. For every node its edge-attributes get aggregated and inserted as node-attribute. After using this command the file can also be visualized inside the visualization, because the edgefilter creates nodes, if they did not exist before.

Usage

ccsh edgefilter [-h] [-o=<outputFile>]
                [--path-separator=<pathSeparator>] FILE

Parameters

      FILE     files to filter
  -h, --help   displays this help and exits
  -o, --output-file=<outputFile>
               output File (or empty for stdout)
      --path-separator=<pathSeparator>
               path separator (default = '/')

Example

ccsh edgefilter edges.cc.json -o visual_edges.cc.json

Merge Filter

Reads the specified files and merges visualisation data.

The first file with visualisation data is used as reference for the merging strategy and a base for the output. The visualisation data in the additional json files, given they have the same API version, are fitted into this reference structure according to a specific strategy. Currently, there are two main strategies:

  • recursive (default): leave structure of additional files. This will also merge optional edges.
  • leaf (beta): fit leaf nodes into reference structure according to their name (and tail of their path), either adding missing leaves (--add-missing) or ignoring them (default)

Both strategies will merge the unique list entries for attributeTypes and blacklist.

Usage

ccsh merge [-ah] [--ignore-case] [--leaf] [-nc] [--recursive]
           [-o=<outputFile>] FILE or FOLDER...

Parameters

      FILE or FOLDER...   files to merge
  -a, --add-missing       enable adding missing nodes to reference
  -h, --help              displays this help and exits
      --ignore-case       ignores case when checking node names
      --leaf              leaf merging strategy
      -nc, --not-compressed
                          save uncompressed output File
  -o, --output-file=<outputFile>
                          output File (or empty for stdout)
      --recursive         recursive merging strategy (default)

Examples

ccsh merge file1.cc.json ../foo/file2.cc.json -o=test.cc.json
ccsh merge file1.cc.json ../foo/file2.cc.json -o=test.cc.json --leaf --add-missing
ccsh merge file1.cc.json ../foo/ -o=test.cc.json

(Merges all project files in foo with the reference file)

Structure Modifier

The Structure Modifier is used to modify the structure of .cc.json files. It enables to:

  • remove nodes from a project. The resulting project will not include these nodes and their children.
  • declare a node as root. This means that the chosen node will become the root node of the resulting sub-project.
  • move nodes within the project. All children of the source node will be transferred to the destination node.
  • print the hierarchy of the project.

The edges and blacklist entries associated with moved/removed nodes will be altered as well, while all attribute types will be copied.

Usage

ccsh modify [-h] [-f=<moveFrom>] [-o=<outputFile>]
            [-p=<printLevels>] [-s=<setRoot>] [-t=<moveTo>]
            [-r=<remove>...]... [FILE]

Parameters

      [FILE]                        input project file
  -f, --move-from=<moveFrom>        move nodes in project folder...
  -h, --help                        displays this help and exits
  -o, --output-file=<outputFile>    output File (or empty for stdout)
  -p, --print-levels=<printLevels>  show first x layers of project hierarchy
  -r, --remove=<remove>...          node(s) to be removed
  -s, --set-root=<setRoot>          path within project to be extracted
  -t, --move-to=<moveTo>            ... move nodes to destination folder

Examples

ccsh modify foo.cc.json -p=2
ccsh modify foo.cc.json --remove=/root/foo --remove=/root/bar/
ccsh modify foo.cc.json --move-from=/root/foo --move-to=/root/bar -output-file=project.cc.json
ccsh modify foo.cc.json --set-root=/root/foo/

Piped input

Instead of providing a cc.json file as input, a project can also be piped to the filter:

cat demo.cc.json | ccsh modify -p=2

Exporters

CSV Export

Generates CSV file with header from visualization data

Conventions for csv output:

  • Every node with attributes contributes one line
  • Column named path contains the hierarchical data of the node, separated via /
  • Column named name contains the name of the node
  • Column named type contains the type of the node
  • Columns named Dir0, Dir1, … contain the split hierarchical data of the node for convenience
  • The other columns contain the attributes of the nodes

Usage

ccsh csvexport [-h] [--depth-of-hierarchy=<maxHierarchy>]
               [-o=<outputFile>] FILE...

Parameters

      FILE...   json files
      --depth-of-hierarchy=<maxHierarchy>
                depth of the hierarchy
  -h, --help    displays this help and exits
  -o, --output-file=<outputFile>
                output File (or empty for stdout)

Example

ccsh csvexport visual.cc.json

Updated: