arcana (noun):

1. secret or arcane knowledge, acquired or understood by only a few.
2. software architecture analyses.

Arcana performs various analyses on a software architectural knowledge base represented in a knowledge graph.

Usage Instructions

Installing Dependencies

To install the necessary dependencies, run the following command:

pip install -r requirements.txt

Running Arcana

To execute Arcana, use the following command:

python -m arcana [--config CONFIG] [--use-seeder] command

We recommend redirecting stderr to a log file by appending 2> log.txt to the end of the command line.

CONFIG is an optional argument that specifies the path to the configuration file. If not provided, the default path config.ini is used. Refer to config.ini.example for more information about the configuration.

The command argument can be one of the following:

• metrics: This command computes metrics for the graph nodes and adds the computed metrics to the node's properties. Currently, the only supported metric is the dependency profile.

• llm: This command uses a large language model API (specified in the llm section of the configuration file) to analyze and add properties to the graph nodes, including:

  • description: A one-sentence summary of packages, classes, and methods/constructors.
  • roleStereotype: A classification of classes into one of Wirfs-Brock's role stereotypes.
  • layer: A classification of packages, classes, and methods/constructors into architectural layers.

  Currently, this command adds all the properties above, i.e., there is no way to select only one or two properties to add to the graph.

Commands can be chained together in a pipeline by specifying them in succession, separated by a dash (-). For example, python -m arcana metrics-llm will first execute the metrics command on the input graph, and then the llm command on the graph produced by the metrics command.

For more information on the commands and how they work, refer to Architecture.

Input

Arcana typically takes as input a knowledge graph as described in this paper, in a specific JSON format. This input is specified in the configuration file.

[project]
name=<project name here>
desc=<project description here>
input=<specify input here>
...

The input field can either be a path to a JSON file containing the graph data, or stdin to read the JSON text from standard input. This is useful when you want to use the output of another program that produces the graph data.

Using a Seeder

If you don’t have a graph ready and want to specify a source directory as an input, you can use a seeder by passing --use-seeder as a command line argument to Arcana. Currently, the only supported seeder is javapers. The configuration for javapers can be found in the seeder section of the configuration file. Ensure that you specify the correct path to the Java executable and the javapers JAR file:

[seeder]
command={javaexe} -jar {jarfile} -i {input} -a -n {name} -f json
javaexe=./javapers/jdk-17.0.11+9-jre/bin/java.exe
jarfile=./javapers/javapers-1.1.2-jar-with-dependencies.jar

In this case, the input field in the project section should be a directory that contains the Java source files. You can specify multiple directories by separating each directory with a plus sign (+), like so:

[project]
input=/path/to/src1/+/path/to/src2/
...

Output

Similar to the input, the output can be written to a file or to standard output, based on the output configuration in the project section. The value of the output field can thus be either a path to a file or stdout.

[project]
output=<specify output here>
...

Visualizing the Output

The resulting output, in the same format as the input graph (i.e., a specific JSON format), can be visualized in ClassViz. To do so, save the output of Arcana as a file, then, in ClassViz, click on the top-left button (“Upload JSON”) and select the file created by Arcana.

Please note, however, that ClassViz is exploratory in nature and may be unstable. In particular, it can take a long time to load a large graph file and to calculate the layout. A more mature visualizer is currently under development.