This folder contains standalone scripts for measuring the structure and quality of a Python repository.

• extract_architecture.py extracts classes, functions, modules, internal dependencies, and an architecture graph.
• radon_metrics.py computes cyclomatic complexity, Maintainability Index, and Halstead metrics.
• coupling.py computes a simplified CBO coupling score.
• cohesion.py computes an approximate LCOM cohesion score.
• repository_summary.py generates a repository-wide summary.
• compare_repositories.py compares two repositories or two prepared reports and generates comparison charts.
• generate_report.py aggregates the outputs and produces CSV, Excel, and charts.
• run_all.py runs the full workflow in one command and writes everything to a user-defined output folder.

Optional dependencies used by the evaluation scripts:

• radon
• networkx
• pandas
• matplotlib
• openpyxl

Use --root when the repository is already available locally. Use --repo and --branch when you want the script to clone a remote repository first. If the repository is already cloned internally, pass only the local path with --root.

If you want to run everything at once, use run_all.py and choose the output folder with --output-dir.

Examples:

• Local repository already cloned:

python3 evaluation/repository_summary.py --root /home/amine/HydroModPy-Hackathon

• Remote repository to clone on demand:

python3 evaluation/repository_summary.py \
	--repo https://github.com/ORG/REPO.git \
	--branch main

python3 evaluation/repository_summary.py \
	--root . \
	--output evaluation/out/summary.json \
	--csv evaluation/out/summary.csv

From a remote repository:

python3 evaluation/repository_summary.py \
	--repo https://github.com/ORG/REPO.git \
	--branch main \
	--output evaluation/out/summary.json \
	--csv evaluation/out/summary.csv

python3 evaluation/radon_metrics.py \
	--root . \
	--output evaluation/out/radon.json

From a remote repository:

python3 evaluation/radon_metrics.py \
	--repo https://github.com/ORG/REPO.git \
	--branch main \
	--output evaluation/out/radon.json

python3 evaluation/coupling.py \
	--root . \
	--output evaluation/out/coupling.json

python3 evaluation/cohesion.py \
	--root . \
	--output evaluation/out/cohesion.json

python3 evaluation/extract_architecture.py \
	--root . \
	--output evaluation/out/architecture.json \
	--graph-output evaluation/out/architecture_graph.png

You can also export the architecture graph as GraphML or JSON by changing the file extension of --graph-output.

If you already have JSON outputs in one folder:

python3 evaluation/generate_report.py \
	--input-dir evaluation/out \
	--output-dir evaluation/report \
	--excel evaluation/report/evaluation.xlsx

Directly from a remote repository:

python3 evaluation/generate_report.py \
	--repo https://github.com/ORG/REPO.git \
	--branch main \
	--output-dir evaluation/report \
	--excel evaluation/report/evaluation.xlsx

For a repository that is already cloned locally:

python3 evaluation/run_all.py \
	--root /home/amine/HydroModPy-Hackathon \
	--output-dir /home/amine/HydroModPy-Hackathon/hackathon

For a remote repository:

python3 evaluation/run_all.py \
	--repo https://github.com/ORG/REPO.git \
	--branch main \
	--output-dir /home/amine/HydroModPy-Hackathon/hackathon

This creates:

• /output-dir/raw/ with the JSON outputs and the architecture graph.
• /output-dir/report/ with CSV files and charts.
• /output-dir/evaluation.xlsx with the Excel report.

Generate a JSON comparison and the main bar chart:

python3 evaluation/compare_repositories.py \
	--left-repo https://github.com/ORG/REPO-A.git --left-branch main \
	--right-repo https://github.com/ORG/REPO-B.git --right-branch develop \
	--output evaluation/out/comparison.json \
	--chart evaluation/out/comparison_bar_chart.png

Generate the complete comparison bundle with all requested charts:

python3 evaluation/compare_repositories.py \
	--left-repo https://github.com/ORG/REPO-A.git --left-branch main \
	--right-repo https://github.com/ORG/REPO-B.git --right-branch develop \
	--left-label hackathon \
	--right-label legacy \
	--output evaluation/out/comparison.json \
	--output-dir evaluation/out/charts

You can use --left-label and --right-label to force the names shown in the charts.

This will generate:

• bar_chart.png for direct metric comparison.
• boxplot_complexity.png for the cyclomatic complexity distribution.
• radar_chart.png for Complexity, Maintainability, CBO, LCOM, and Halstead.
• dependency_heatmap.png for module dependencies.
• architecture_graph.png for the NetworkX architecture graph.

Run the scripts in this order when you want a complete analysis of one repository:

1. repository_summary.py to collect the basic repository structure.
2. radon_metrics.py to compute complexity, Maintainability Index, and Halstead.
3. coupling.py to compute the CBO coupling score.
4. cohesion.py to compute the LCOM approximation.
5. extract_architecture.py to build the architecture data and graph.
6. generate_report.py to aggregate the results and create CSV, Excel, and charts.

When comparing two repositories, run:

1. compare_repositories.py if you already have two repositories or two summary files.
2. generate_report.py if you want a complete report folder for one repository.

mkdir -p evaluation/out evaluation/report
python3 evaluation/repository_summary.py --root . --output evaluation/out/summary.json --csv evaluation/out/summary.csv
python3 evaluation/radon_metrics.py --root . --output evaluation/out/radon.json
python3 evaluation/coupling.py --root . --output evaluation/out/coupling.json
python3 evaluation/cohesion.py --root . --output evaluation/out/cohesion.json
python3 evaluation/extract_architecture.py --root . --output evaluation/out/architecture.json --graph-output evaluation/out/architecture_graph.png
python3 evaluation/generate_report.py --input-dir evaluation/out --output-dir evaluation/report --excel evaluation/report/evaluation.xlsx