gdcruiser 1.2.0

Dependency analyzer for Godot/GDScript projects

gdcruiser

A dependency analyzer for Godot/GDScript projects. Scans your project to build a dependency graph, detect circular dependencies, and export visualizations.

Features

• Analyzes .gd (GDScript) and .tscn (scene) files
• Detects circular dependencies
• Resolves class_name declarations to map symbolic inheritance
• Multiple output formats: human-readable text, JSON, and GraphViz DOT
• Returns non-zero exit code when cycles are detected (CI-friendly)

Installation

Requires Python 3.13+.

pip install gdcruiser

Or with uv:

uv tool install gdcruiser

Usage

gdcruiser [-h] [-f {text,json,dot}] [-o FILE] [--no-cycles] [-v] [path]

Option	Description
path	Godot project path (default: current directory)
-f, --format	Output format: text (default), json, or dot
-o, --output	Write output to file instead of stdout
--no-cycles	Skip cycle detection
-v, --verbose	Verbose output

Examples

Analyze the current directory:

gdcruiser .

Analyze a specific project and output JSON:

gdcruiser /path/to/godot/project -f json

Generate a GraphViz DOT file:

gdcruiser . -f dot -o deps.dot
dot -Tpng deps.dot -o deps.png

Output Formats

Text (default)

============================================================
GDScript Dependency Analysis
============================================================

Modules: 9
Dependencies: 8

----------------------------------------
CIRCULAR DEPENDENCIES (1 found)
----------------------------------------

Cycle 1:
  -> res://cycle_b.gd
  -> res://cycle_a.gd
  -> res://cycle_b.gd (back to start)

----------------------------------------
MODULE DEPENDENCIES
----------------------------------------

res://player.gd
  class_name: Player
  extends_class: res://base_entity.gd:2
  preload: res://inventory.gd:5

JSON

{
  "graph": {
    "modules": {
      "res://player.gd": {
        "path": "res://player.gd",
        "class_name": "Player",
        "dependencies": [
          {
            "target": "res://base_entity.gd",
            "type": "extends_class",
            "line": 2,
            "resolved": true
          }
        ]
      }
    },
    "stats": {
      "module_count": 9,
      "dependency_count": 8
    }
  },
  "cycles": [],
  "symbols": {
    "Player": "res://player.gd"
  },
  "errors": []
}

GraphViz DOT

digraph dependencies {
    rankdir=LR;
    node [shape=box, fontname="monospace"];

    "res://player.gd" [label="Player\nplayer.gd"];
    "res://base_entity.gd" [label="BaseEntity\nbase_entity.gd"];

    "res://player.gd" -> "res://base_entity.gd" [label="extends"];
}

Nodes involved in cycles are highlighted in red.

Supported Dependency Patterns

gdcruiser detects the following GDScript patterns:

Pattern	Example
extends (path)	extends "res://path/to/script.gd"
extends (class)	extends ClassName
class_name	class_name MyClass
preload()	preload("res://path/to/file.gd")
load()	load("res://path/to/file.gd")

For .tscn files, it detects scripts attached to nodes via [ext_resource].

Development

Install dependencies:

uv sync

Set up pre-commit hooks:

uv run pre-commit install

This installs hooks for pre-commit, commit-msg, and post-checkout stages. On every commit the hooks will:

• Fix trailing whitespace and line endings
• Lint and format with Ruff
• Run the test suite with pytest
• Enforce Conventional Commits for commit messages

Run the CLI:

uv run gdcruiser

Run tests:

uv run pytest

Run linter:

uv run ruff check .

Format code:

uv run ruff format .